שיפור בדיקת הקוד בעזרת הערות

שימוש בכלים לבדיקת קוד, כמו lint, יכול לעזור לכם לאתר בעיות ולשפר את הקוד, אבל כלי הבדיקה יכולים להסיק מסקנות רבות בלבד. לדוגמה, מזהי המשאבים של Android משתמשים ב-int כדי לזהות מחרוזות, גרפיקה, צבעים וסוגים אחרים של משאבים, כך שכלי הבדיקה לא יכולים לדעת מתי ציינת משאב מחרוזת במקום צבע. המצב הזה עלול לגרום לכך שהאפליקציה תתבצע באופן שגוי או לא תפעל בכלל, גם אם משתמשים בבדיקת הקוד.

הערות מאפשרות לספק רמזים לכלים לבדיקת קוד, כמו lint, כדי לזהות בעיות קוד מתוחכמות יותר. ההערות מתווספות בתור תגי מטא-נתונים שמצרפים למשתנים, לפרמטרים ולערכים המוחזרים כדי לבדוק את ערכי ההחזרה של השיטות, את הפרמטרים המועברים, את המשתנים המקומיים ואת השדות. כשמשתמשים בהערות עם כלים לבדיקת קוד, אפשר לזהות בעיות כמו חריגות של נקודות הצבעה ל-null וקונפליקטים מסוג משאבים.

Android תומך במגוון הערות באמצעות ספריית ההערות של Jetpack. אפשר לגשת לספרייה דרך החבילה androidx.annotation.

הערה: אם למודול יש תלות במעבד הערות, צריך להשתמש בהגדרת התלות kapt או ksp ל-Kotlin, או בהגדרת התלות annotationProcessor ל-Java כדי להוסיף את התלות הזו.

הוספת הערות לפרויקט

כדי להפעיל הערות בפרויקט, צריך להוסיף לספרייה או לאפליקציה את התלות androidx.annotation:annotation. כשמריצים בדיקת קוד או משימת lint, כל הערה שמוסיפים נבדקת.

הוספת התלות בספרייה Jetpack Annotations

הספרייה של Jetpack Annotations מתפרסמת ב-Maven Repository של Google. כדי להוסיף את ספריית Jetpack Anotations לפרויקט, צריך לכלול את השורה הבאה בבלוק dependencies בקובץ build.gradle או בקובץ build.gradle.kts:

KotlinGroovy

dependencies {
    implementation("androidx.annotation:annotation:1.9.1")
}

dependencies {
    implementation 'androidx.annotation:annotation:1.9.1'
}

לאחר מכן, בסרגל הכלים או בהתראת הסנכרון שמופיעה, לוחצים על סנכרון עכשיו.

אם אתם משתמשים בהערות במודול הספרייה שלכם, ההערות נכללות כחלק מ-artifact של Android Archive ‏ (AAR) בפורמט XML בקובץ annotations.zip. הוספת התלות של androidx.annotation לא יוצרת תלות של משתמשים ב-downstream בספרייה שלכם.

הערה: אם אתם משתמשים בספריות אחרות של Jetpack, יכול להיות שלא תצטרכו להוסיף את התלות ב-androidx.annotation. ספריות רבות אחרות של Jetpack תלויות בספריית ההערות, כך שיכול להיות שכבר יש לכם גישה להערות.

רשימה מלאה של ההערות שכלולות במאגר של Jetpack מופיעה במאמר העזרה בנושא ספריית ההערות של Jetpack. אפשר גם להשתמש בתכונת ההשלמה האוטומטית כדי להציג את האפשרויות הזמינות להצהרה import androidx.annotation..

הרצת בדיקות קוד

כדי להתחיל בדיקה של קוד מ-Android Studio, שכוללת אימות של הערות ובדיקת שגיאות אוטומטית, בוחרים באפשרות Analyze > Inspect Code בתפריט. ב-Android Studio מוצגות הודעות התנגשות כדי לסמן בעיות פוטנציאליות כאשר הקוד מתנגש עם הערות וכדי להציע פתרונות אפשריים.

אפשר גם לאכוף את ההערות על ידי הרצת המשימה lint באמצעות שורת הפקודה. האפשרות הזו יכולה לעזור לסימון בעיות בשרת אינטגרציה רציפה (CI), אבל המשימה lint לא אוכפת הערות null (כפי שמתואר בקטע הבא). רק Android Studio. מידע נוסף על הפעלה והרצה של בדיקות לאיתור שגיאות זמין במאמר שיפור הקוד באמצעות בדיקות לאיתור שגיאות בקוד.

על אף שהתנגשויות בין הערות יוצרות אזהרות, האזהרות האלה לא מונעות את ההידור של האפליקציה.

הערות על ערכים null

הערות על ערכים null יכולות להיות שימושיות בקוד Java כדי לאכוף אם ערכים יכולים להיות null. הם פחות שימושיים בקוד Kotlin, כי ל-Kotlin יש כללים מובנים של תכונות Nullable, שמופעלים בזמן הידור.

מוסיפים את ההערות @Nullable ו-@NonNull כדי לבדוק אם משתנה, פרמטר או ערך מוחזר מסוימים הם null. ההערה @Nullable מציינת משתנה, פרמטר או ערך מוחזר שיכולים להיות null. @NonNull מציין משתנה, פרמטר או ערך מוחזר שלא יכול להיות null.

לדוגמה, אם משתנה מקומי שמכיל ערך null מועבר כפרמטר לשיטה עם ההערה @NonNull שמצורפת לפרמטר הזה, ה-build של הקוד יוצר אזהרה לגבי התנגשויות של ערכים שאינם null. כמו כן, כשמנסים להפנות לתוצאה של method שסומנה על ידי @Nullable בלי לבדוק קודם אם התוצאה היא null, מתקבלת אזהרה לגבי הערך ריק. מומלץ להשתמש ב-@Nullable בערך המוחזר של שיטה רק אם צריך לבצע בדיקת null מפורשת בכל שימוש בשיטה.

הדוגמה הבאה ממחישה את האפשרות של ערך null. קוד הדוגמה ב-Kotlin לא משתמש בתיוג @NonNull כי הוא מתווסף באופן אוטומטי לקוד הבייט שנוצר כשמציינים סוג שאינו nullable. בדוגמה ל-Java נעשה שימוש בהערה @NonNull על הפרמטרים context ו-attrs כדי לבדוק שערכי הפרמטרים שהועברו הם לא null. בנוסף, הוא בודק שהשיטה onCreateView() עצמה לא מחזירה null:

KotlinJava

...
    /** Annotation not used because of the safe-call operator(?)**/
    override fun onCreateView(
            name: String?,
            context: Context,
            attrs: AttributeSet
    ): View? {
        ...
    }
...

import androidx.annotation.NonNull;
...
    /** Add support for inflating the <fragment> tag. **/
    @NonNull
    @Override
    public View onCreateView(String name, @NonNull Context context,
      @NonNull AttributeSet attrs) {
      ...
      }
...

ניתוח של יכולת האפסיות

ב-Android Studio יש תמיכה בהפעלת ניתוח של סטטוס הערך null כדי להסיק באופן אוטומטי ולהוסיף הערות לגבי סטטוס הערך null בקוד. ניתוח של יכולת האפסיות סורק את החוזים בהיררכיות השיטות בקוד כדי לזהות:

• שיטות להתקשרות שיכולות להחזיר ערך null.
• שיטות שלא אמורות להחזיר ערך null.
• משתנים כמו שדות, משתנים מקומיים ופרמטרים, שיכולים להיות null.
• משתנים כמו שדות, משתנים מקומיים ופרמטרים, לא יכולים להכיל ערך null.

לאחר מכן, המערכת תוסיף באופן אוטומטי את ההערות הרלוונטיות של הערך null למיקומים שזוהו.

כדי להריץ ניתוח של יכולת הערך האפסי ב-Android Studio, בוחרים באפשרות Analyze (ניתוח) > Infer Nullity (הסקת יכולת הערך האפסי). Android Studio מוסיף את ההערות @Nullable ו-@NonNull של Android למיקומים שזוהו בקוד. אחרי שמריצים ניתוח null, מומלץ לאמת את ההערות שהוחדרו.

הערה: כשמוסיפים הערות null, יכול להיות שההשלמה האוטומטית תציע את ההערות @Nullable ו-@NotNull של IntelliJ במקום הערות ה-null ב-Android, ויכול להיות שיתבצע ייבוא אוטומטי של הספרייה המתאימה. עם זאת, בודק ה-lint של Android Studio מחפש רק את ההערות של null ב-Android. כשמאמתים את ההערות, צריך לוודא שהפרויקט משתמש בהערות ה-null ב-Android, כדי שבודק השגיאות יוכל להודיע לך על כך כראוי במהלך בדיקת הקוד.

הערות על משאבים

אימות סוגי המשאבים יכול להיות שימושי כי הפניות של Android למשאבים, כמו משאבים מסוג drawable ומשאבים מסוג string, מועברות כמספרים שלמים.

קוד שמצפה שפרמטר יפנה לסוג ספציפי של משאב, כמו String, יכול להעביר את סוג העזר המצופה של int, אבל בפועל להפנות לסוג אחר של משאב, כמו משאב R.string.

לדוגמה, מוסיפים הערות @StringRes כדי לבדוק אם פרמטר של משאב מכיל הפניה ל-R.string, כפי שמוצג כאן:

KotlinJava

abstract fun setTitle(@StringRes resId: Int)

public abstract void setTitle(@StringRes int resId)

במהלך בדיקת הקוד, ההערה יוצרת אזהרה אם לא מועברת הפניה ל-R.string בפרמטר.

אפשר להוסיף הערות לסוגים אחרים של משאבים, כמו @DrawableRes,‏ @DimenRes,‏ @ColorRes ו-@InterpolatorRes, באמצעות אותו פורמט הערה ולהריץ אותן במהלך בדיקת הקוד.

אם הפרמטר תומך במספר סוגי משאבים, אפשר להוסיף יותר מתווית אחת של סוג משאב לפרמטר נתון. משתמשים ב-@AnyRes כדי לציין שהפרמטר המתויג יכול להיות כל סוג של משאב R.

למרות שאפשר להשתמש ב-@ColorRes כדי לציין שפרמטר צריך להיות משאב צבע, מספר שלם של צבע (בפורמט RRGGBB או AARRGGBB) לא מזוהה כמשאב של צבעים. במקום זאת, צריך להשתמש בהערה @ColorInt כדי לציין שפרמטר חייב להיות מספר שלם של צבע. כלי ה-build יסמנו קוד שגוי שמעביר למתודות עם הערות מזהה משאב של צבע, כמו android.R.color.black, במקום מספר שלם של צבע.

הערות בשרשור

הערות בשרשור בודקות אם קוראים לשיטה מסוג שרשור ספציפי. יש תמיכה בהערות הבאות בשרשור:

• @MainThread
• @UiThread
• @WorkerThread
• @BinderThread
• @AnyThread

כלי ה-build מתייחסים להערות @MainThread ו-@UiThread כאל ערכים שניתן להחליף ביניהם, כך שאפשר להפעיל שיטות @UiThread משיטות @MainThread ולהפך. עם זאת, יכול להיות ששרשור של ממשק משתמש יהיה שונה מהשרשור הראשי, במקרה של אפליקציות מערכת עם כמה תצוגות בשרשור שונה. לכן, צריך להוסיף הערות לשיטות שמשויכות להיררכיית התצוגה של האפליקציה באמצעות @UiThread, ולהוסיף הערות רק לשיטות שמשויכות למחזור החיים של האפליקציה באמצעות @MainThread.

אם לכל השיטות בכיתה יש אותה דרישת תהליך, אפשר להוסיף לכיתה הערה אחת לגבי תהליך כדי לוודא שכל השיטות בכיתה נקראות מאותו סוג של תהליך.

שימוש נפוץ בהערות של שרשורים הוא לוודא שהשיטות או המחלקות שמסומנות באמצעות @WorkerThread נקראים רק משרשור מתאים ברקע.

הערות לגבי מגבלת ערך

משתמשים בהערות @IntRange,‏ @FloatRange ו-@Size כדי לאמת את הערכים של הפרמטרים המועברים. האפשרויות @IntRange ו-@FloatRange הכי שימושיות כשמחילים אותן על פרמטרים שבהם יש סיכוי גבוה שהמשתמשים יבחרו טווח שגוי.

ההערה @IntRange מאמתת שערך פרמטר ארוך או מספר שלם נמצאים בטווח שצוין. הדוגמה הבאה מציינת שהפרמטר alpha חייב להכיל ערך של מספר שלם בין 0 ל-255:

KotlinJava

fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }

public void setAlpha(@IntRange(from=0,to=255) int alpha) { ... }

ההערה @FloatRange בודקת אם ערך פרמטר מסוג float או double נמצא בטווח מסוים של ערכים של נקודות צפות. הדוגמה הבאה מציינת שהפרמטר alpha חייב להכיל ערך מסוג מספר ממשי (float) מ-0.0 עד 1.0:

KotlinJava

fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}

public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}

ההערה @Size בודקת את הגודל של אוסף או מערך או את האורך של מחרוזת. אפשר להשתמש בהערה @Size כדי לאמת את המאפיינים הבאים:

• גודל מינימלי, למשל @Size(min=2)
• גודל מקסימלי, למשל @Size(max=2)
• גודל מדויק, למשל @Size(2)
• מספר שהגודל חייב להיות כפולה שלו, למשל @Size(multiple=2)

לדוגמה, @Size(min=1)בודקת אם אוסף לא ריק, ו-@Size(3) מאמתת שמערך מכיל שלושה ערכים בדיוק.

בדוגמה הבאה מצוין שמערך location חייב להכיל רכיב אחד לפחות:

KotlinJava

fun getLocation(button: View, @Size(min=1) location: IntArray) {
    button.getLocationOnScreen(location)
}

void getLocation(View button, @Size(min=1) int[] location) {
    button.getLocationOnScreen(location);
}

הערות לגבי הרשאות

משתמשים בהערה @RequiresPermission כדי לאמת את ההרשאות של מבצע הקריאה החוזרת של השיטה. כדי לבדוק הרשאה אחת מתוך רשימה של הרשאות תקינות, משתמשים במאפיין anyOf. כדי לבדוק קבוצה של הרשאות, משתמשים במאפיין allOf. בדוגמה הבאה מופיעה הערה על השיטה setWallpaper() כדי לציין שלמבצע הקריאה החוזרת (caller) של השיטה צריכה להיות ההרשאה permission.SET_WALLPAPERS:

KotlinJava

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
@Throws(IOException::class)
abstract fun setWallpaper(bitmap: Bitmap)

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
public abstract void setWallpaper(Bitmap bitmap) throws IOException;

בדוגמה הבאה, למבצע הקריאה ל-method‏ copyImageFile() צריכה להיות גם גישה לקריאה לאחסון החיצוני וגם גישה לקריאה למטא-נתונים של המיקום בקובץ התמונה שהועתק:

KotlinJava

@RequiresPermission(allOf = [
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.ACCESS_MEDIA_LOCATION
])
fun copyImageFile(dest: String, source: String) {
    ...
}

@RequiresPermission(allOf = {
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.ACCESS_MEDIA_LOCATION})
public static final void copyImageFile(String dest, String source) {
    //...
}

להרשאות של כוונות, צריך להציב את דרישת ההרשאה בשדה המחרוזת שמגדיר את שם הפעולה של הכוונה:

KotlinJava

@RequiresPermission(android.Manifest.permission.BLUETOOTH)
const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"

@RequiresPermission(android.Manifest.permission.BLUETOOTH)
public static final String ACTION_REQUEST_DISCOVERABLE =
            "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";

אם יש צורך בהרשאות נפרדות לקריאה ולכתיבה לספקים של תוכן, צריך לעטוף כל הרשאה בתיאור @RequiresPermission.Read או @RequiresPermission.Write:

KotlinJava

@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS))
val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")

@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS))
public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");

הרשאות עקיפות

אם ההרשאה תלויה בערך הספציפי שסופק לפרמטר של ה-method, אפשר להשתמש ב-@RequiresPermission בפרמטר עצמו בלי לפרט את ההרשאות הספציפיות. לדוגמה, השיטה startActivity(Intent) משתמשת בהרשאה עקיפה ב-intent שמועברת לשיטה:

KotlinJava

abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)

public abstract void startActivity(@RequiresPermission Intent intent, @Nullable Bundle)

כשמשתמשים בהרשאות עקיפות, כלי ה-build מבצעים ניתוח של זרימת הנתונים כדי לבדוק אם לארגומנט שמועבר ל-method יש הערות @RequiresPermission. לאחר מכן הם אוכפים הערה קיימת מהפרמטר בשיטה עצמה. בדוגמה startActivity(Intent), ההערות בכיתה Intent גורמות לאזהרות על שימוש לא חוקי ב-startActivity(Intent) כשמעבירים לשיטה כוונה (intent) ללא ההרשאות המתאימות, כפי שמוצג באיור 1.

איור 1. האזהרה שנוצרה מהערה עקיפה על ההרשאות בשיטה startActivity(Intent).

כלי ה-build יוצרים את האזהרה ב-startActivity(Intent) מההערה על שם פעולת ה-Intent התואם בכיתה Intent:

KotlinJava

@RequiresPermission(Manifest.permission.CALL_PHONE)
const val ACTION_CALL = "android.intent.action.CALL"

@RequiresPermission(Manifest.permission.CALL_PHONE)
public static final String ACTION_CALL = "android.intent.action.CALL";

במקרה הצורך, אפשר להחליף את @RequiresPermission ב[e-mail] או ב[e-mail] כשכותבים הערה על פרמטר של שיטה. עם זאת, בהרשאות עקיפות אסור להשתמש ב-@RequiresPermission בשילוב עם ההערות של הרשאות הקריאה או הכתיבה.

הערות לגבי ערכים מוחזרים

משתמשים בהערה @CheckResult כדי לוודא שאכן נעשה שימוש בתוצאה או בערך המוחזר של השיטה. במקום להוסיף הערה @CheckResult לכל שיטה שאינה void, מוסיפים את ההערה כדי להבהיר את התוצאות של שיטות שעלולות לבלבל.

לדוגמה, מפתחי Java חדשים חושבים בטעות שלפעמים <String>.trim() מסיר רווחים מהמחרוזת המקורית. הוספת הערה לשיטה עם @CheckResult מסמנת שימוש ב-<String>.trim() שבו מבצע הקריאה לא עושה דבר עם הערך המוחזר של השיטה.

בדוגמה הבאה מתווספת הערה לשיטה checkPermissions() כדי לבדוק אם יש למעשה הפניה לערך המוחזר של השיטה. בנוסף, הוא מציין את השיטה enforcePermission() בתור השיטה שצריך להציע למפתח כתחליף:

KotlinJava

@CheckResult(suggest = "#enforcePermission(String,int,int,String)")
abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int

@CheckResult(suggest="#enforcePermission(String,int,int,String)")
public abstract int checkPermission(@NonNull String permission, int pid, int uid);

הערות CallSuper

משתמשים בהערה @CallSuper כדי לוודא ששיטת החלפה שולחת קריאה לסופר-הטמעה של השיטה.

בדוגמה הבאה מתווספת הערה לשיטה onCreate() כדי לוודא שכל הטמעות השיטות שמחליפות אותה יקראו ל-super.onCreate():

KotlinJava

@CallSuper
override fun onCreate(savedInstanceState: Bundle?) {
}

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

הערות של טיפוס נתונים מוגדר מראש

הערות של טיפוס נתונים מותאם אישית בודקות אם פרמטר, ערך מוחזר או שדה מסוימים מפנים לקבוצה ספציפית של קבועים. הם גם מאפשרים להשלמת הקוד להציע באופן אוטומטי את הקבועים המותרים.

אפשר להשתמש בהערות @IntDef ו-@StringDef כדי ליצור הערות ממוספרות של קבוצות של מספרים שלמים ומחרוזות, כדי לאמת סוגים אחרים של הפניות לקוד.

בהערות מסוג Typedef נעשה שימוש ב-@interface כדי להצהיר על סוג ההערה החדש שמכיל את המספרים. ההערות @IntDef ו-@StringDef, יחד עם הערה @Retention, מוסיפות הערה להערה החדשה והן נחוצות להגדרת הסוג המנומר. ההערה @Retention(RetentionPolicy.SOURCE) מורה למהדר שלא לאחסן את נתוני ההערות הממוספרים בקובץ .class.

בדוגמה הבאה מוסבר איך יוצרים הערה שבודקת אם ערך שמוענק כפרמטר של שיטה מפנה לאחת הקבועות שהוגדרו:

KotlinJava

import androidx.annotation.IntDef
//...
// Define the list of accepted constants and declare the NavigationMode annotation.
@Retention(AnnotationRetention.SOURCE)
@IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS)
annotation class NavigationMode

// Declare the constants.
const val NAVIGATION_MODE_STANDARD = 0
const val NAVIGATION_MODE_LIST = 1
const val NAVIGATION_MODE_TABS = 2

abstract class ActionBar {

    // Decorate the target methods with the annotation.
    // Attach the annotation.
    @get:NavigationMode
    @setparam:NavigationMode
    abstract var navigationMode: Int

}

import androidx.annotation.IntDef;
//...
public abstract class ActionBar {
    //...
    // Define the list of accepted constants and declare the NavigationMode annotation.
    @Retention(RetentionPolicy.SOURCE)
    @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
    public @interface NavigationMode {}

    // Declare the constants.
    public static final int NAVIGATION_MODE_STANDARD = 0;
    public static final int NAVIGATION_MODE_LIST = 1;
    public static final int NAVIGATION_MODE_TABS = 2;

    // Decorate the target methods with the annotation.
    @NavigationMode
    public abstract int getNavigationMode();

    // Attach the annotation.
    public abstract void setNavigationMode(@NavigationMode int mode);
}

כשמפתחים את הקוד הזה, נוצרת אזהרה אם הפרמטר mode לא מפנה לאחת הקבועות שהוגדרו (NAVIGATION_MODE_STANDARD,‏ NAVIGATION_MODE_LIST או NAVIGATION_MODE_TABS).

משלבים את @IntDef ואת @IntRange כדי לציין שמספר שלם יכול להיות קבוצה נתונה של קבועים או ערך בתוך טווח.

איך משלבים בין קבועים לדגלים

אם המשתמשים יכולים לשלב את הקבועים המותרים עם דגל (כמו |, &, ^ וכן הלאה), אפשר להגדיר הערה עם המאפיין flag כדי לבדוק אם פרמטר או ערך מוחזר מפנים לדפוס חוקי.

בדוגמה הבאה נוצרת ההערה DisplayOptions עם רשימה של קבועים DISPLAY_ חוקיים:

KotlinJava

import androidx.annotation.IntDef
...

@IntDef(flag = true, value = [
    DISPLAY_USE_LOGO,
    DISPLAY_SHOW_HOME,
    DISPLAY_HOME_AS_UP,
    DISPLAY_SHOW_TITLE,
    DISPLAY_SHOW_CUSTOM
])
@Retention(AnnotationRetention.SOURCE)
annotation class DisplayOptions
...

import androidx.annotation.IntDef;
...

@IntDef(flag=true, value={
        DISPLAY_USE_LOGO,
        DISPLAY_SHOW_HOME,
        DISPLAY_HOME_AS_UP,
        DISPLAY_SHOW_TITLE,
        DISPLAY_SHOW_CUSTOM
})
@Retention(RetentionPolicy.SOURCE)
public @interface DisplayOptions {}

...

כשמפתחים קוד עם דגל הערה, נוצרת אזהרה אם הפרמטר המעוטר או ערך ההחזרה לא מפנים לדפוס תקין.

שמירה של ההערה

ההערה @Keep מבטיחה ששיטה או כיתה עם הערה לא יוסרו כשהקוד ימוזער בזמן ה-build. ההערה הזו בדרך כלל מתווספת ל-methods ולמחלקות שניגשים אליהם דרך השתקפות כדי למנוע מהמהדר לטפל בקוד כשהוא לא בשימוש.

זהירות: השיעורים והשיטות שמוסיפים הערות להם באמצעות @Keep מופיעים תמיד בקובץ ה-APK של האפליקציה, גם אם אף פעם לא מפנים לשיעורים ולשיטות האלה בתוך הלוגיקה של האפליקציה.

כדי שגודל האפליקציה יהיה קטן, כדאי לבדוק אם צריך לשמור כל הערה @Keep באפליקציה. אם משתמשים בהשתקפות כדי לגשת למחלקה או לשיטה עם הערות, צריך להשתמש בתנאי -if בכללי ProGuard, ולציין את המחלקה שמפעילה את הקריאות להחזר.

מידע נוסף על הקטנת הקוד וציון הקוד שלא צריך להסיר זמין במאמר כיווץ, ערפול קוד (obfuscation) ואופטימיזציה של האפליקציה.

הערות של חשיפת קוד

אפשר להשתמש בהערות הבאות כדי לציין את החשיפה של חלקים ספציפיים בקוד, כמו שיטות, כיתות, שדות או חבילות.

הצגת הקוד לצורך בדיקה

ההערה @VisibleForTesting מציינת ששיטה עם הערה גלויה יותר מהרגיל, כדי שאפשר יהיה לבדוק אותה. בהערה הזו יש ארגומנט otherwise אופציונלי, שמאפשר להגדיר את החשיפה של ה-method אם לא צריך להציג אותה לצורך בדיקה. Lint משתמש בארגומנט otherwise כדי לאכוף את רמת החשיפה הרצויה.

בדוגמה הבאה, הערך של myMethod() הוא בדרך כלל private, אבל הוא package-private במהלך בדיקות. בסיווג VisibleForTesting.PRIVATE, איתור שגיאות בקוד יציג הודעה אם מתבצעת קריאה לשיטה הזו מחוץ להקשר שמותר על ידי הגישה של private, למשל מיחידת הידור אחרת.

KotlinJava

@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
fun myMethod() {
    ...
}

@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
void myMethod() { ... }

אפשר גם לציין @VisibleForTesting(otherwise = VisibleForTesting.NONE) כדי לציין ששיטה קיימת רק לצורך בדיקה. הטופס הזה זהה לשימוש ב-@RestrictTo(TESTS). שתיהן מבצעות את אותה בדיקת שגיאות בקוד.

הגבלת API

ההערה @RestrictTo מציינת שהגישה ל-API (חבילת קוד, סוג או שיטה) עם ההערה מוגבלת באופן הבא:

מחלקות משנה

השתמשו בטופס ההערה @RestrictTo(RestrictTo.Scope.SUBCLASSES) כדי להגביל את הגישה ל-API לכיתות משנה בלבד.

רק לכיתות שמרחיבים את המחלקה עם הערות יכולות לגשת ל-API הזה. המאפיין protected ב-Java לא מגביל מספיק, כי הוא מאפשר גישה מחלקות לא קשורות באותה חבילה. בנוסף, יש מקרים שבהם רוצים להשאיר שיטה public בגלל גמישות עתידית, כי אי אפשר ליצור שיטה protected קודמת ושיטה public שעברה שינוי, אבל רוצים לספק רמז שהמחלקה מיועדת לשימוש בתוך המחלקה או מתת-מחלקות בלבד.

ספריות

אפשר להשתמש בטופס ההערה @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) כדי להגביל את הגישה ל-API לספריות שלכם בלבד.

רק לקוד הספרייה שלכם תהיה גישה ל-API עם ההערות. כך תוכלו לא רק לארגן את הקוד בהיררכיית חבילות לפי הצורך, אלא גם לשתף את הקוד בין קבוצה של ספריות קשורות. האפשרות הזו כבר זמינה בספריות של Jetpack שיש בהן הרבה קוד הטמעה שלא מיועד לשימוש חיצוני, אבל צריך להגדיר אותו כ-public כדי לשתף אותו בין הספריות השונות של Jetpack.

בדיקה

כדי למנוע ממפתחים אחרים לגשת לממשקי ה-API לבדיקה, צריך להשתמש בטופס ההערות @RestrictTo(RestrictTo.Scope.TESTS).

רק קוד בדיקה יכול לגשת ל-API עם ההערות. כך תוכלו למנוע מפיתוחים אחרים להשתמש ב-API לצורכי פיתוח, אם אתם מתכוונים להשתמש בו למטרות בדיקה בלבד.