דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

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

Kotlin

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

Groovy

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

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

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

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

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

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

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

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

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

הערות לגבי איפוס

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

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

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

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

Kotlin

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

Java

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 סורק את החוזים בכל היררכיות ה-method בקוד כדי לזהות:

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

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

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

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

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

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

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

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

Kotlin

abstract fun setTitle(@StringRes resId: Int)

Java

public abstract void setTitle(@StringRes int resId)

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

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

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

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

הערות בשרשור

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

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

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

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

הערות לגבי אילוצים של ערכים

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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 חייב להכיל רכיב אחד לפחות:

Kotlin

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

Java

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

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

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

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

Kotlin

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

Java

@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 שמועברת לשיטה:

Kotlin

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

Java

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

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

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

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

Kotlin

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

Java

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

אם צריך, אפשר להחליף את @RequiresPermission ב-@RequiresPermission.Read או ב-@RequiresPermission.Write כשמוסיפים הערות לפרמטר של השיטה. עם זאת, בהרשאות עקיפות אין להשתמש ב-@RequiresPermission בשילוב עם ההערות לקריאה או כתיבה.

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

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

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

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

Kotlin

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

Java

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

הערות CallSuper

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

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

Kotlin

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

Java

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

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

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

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

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

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

Kotlin

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

}

Java

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_:

Kotlin

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
...

Java

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. בדרך כלל מוסיפים את ההערה הזו לשיטות ולכיתות שגולשים אליהן באמצעות רפלקציה, כדי למנוע מהמְהדר להתייחס לקוד כאל קוד שלא בשימוש.

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

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

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

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

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

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

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

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

Kotlin

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

Java

@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.

בדיקה

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

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