שימוש בכלים לבדיקת קוד, כמו 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
:
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:
... /** 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
, כפי שמוצג כאן:
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
, במקום מספר שלם של צבע.
הערות בשרשור
הערות בשרשור בודקות אם קוראים לשיטה מסוג שרשור ספציפי. יש תמיכה בהערות הבאות בשרשור:
כלי ה-build מתייחסים להערות @MainThread
ו-@UiThread
כאל ערכים שניתן להחליף ביניהם, כך שאפשר להפעיל שיטות @UiThread
משיטות @MainThread
ולהפך. עם זאת, יכול להיות ששרשור של ממשק משתמש יהיה שונה מהשרשור הראשי, במקרה של אפליקציות מערכת עם כמה תצוגות בשרשור שונה. לכן, צריך להוסיף הערות לשיטות שמשויכות להיררכיית התצוגה של האפליקציה באמצעות @UiThread
, ולהוסיף הערות רק לשיטות שמשויכות למחזור החיים של האפליקציה באמצעות @MainThread
.
אם לכל השיטות בכיתה יש אותה דרישת תהליך, אפשר להוסיף לכיתה הערה אחת לגבי תהליך כדי לוודא שכל השיטות בכיתה נקראות מאותו סוג של תהליך.
שימוש נפוץ בהערות של שרשורים הוא לוודא שהשיטות או המחלקות שמסומנות באמצעות @WorkerThread
נקראים רק משרשור מתאים ברקע.
הערות לגבי מגבלת ערך
משתמשים בהערות @IntRange
, @FloatRange
ו-@Size
כדי לאמת את הערכים של הפרמטרים המועברים. האפשרויות @IntRange
ו-@FloatRange
הכי שימושיות כשמחילים אותן על פרמטרים שבהם יש סיכוי גבוה שהמשתמשים יבחרו טווח שגוי.
ההערה @IntRange
מאמתת שערך פרמטר ארוך או מספר שלם נמצאים בטווח שצוין. הדוגמה הבאה מציינת שהפרמטר alpha
חייב להכיל ערך של מספר שלם בין 0 ל-255:
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:
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
חייב להכיל רכיב אחד לפחות:
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
:
@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()
צריכה להיות גם גישה לקריאה לאחסון החיצוני וגם גישה לקריאה למטא-נתונים של המיקום בקובץ התמונה שהועתק:
@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) { //... }
להרשאות של כוונות, צריך להציב את דרישת ההרשאה בשדה המחרוזת שמגדיר את שם הפעולה של הכוונה:
@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
:
@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 שמועברת לשיטה:
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
:
@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
ב-@RequiresPermission.Read
או ב-@RequiresPermission.Write
כשכותבים הערה על פרמטר של שיטה. עם זאת, בהרשאות עקיפות אסור להשתמש ב-@RequiresPermission
בשילוב עם ההערות של הרשאות הקריאה או הכתיבה.
הערות לגבי ערכים מוחזרים
משתמשים בהערה @CheckResult
כדי לוודא שאכן נעשה שימוש בתוצאה או בערך המוחזר של השיטה. במקום להוסיף הערה @CheckResult
לכל שיטה שאינה void, מוסיפים את ההערה כדי להבהיר את התוצאות של שיטות שעלולות לבלבל.
לדוגמה, מפתחי Java חדשים חושבים בטעות שלפעמים <String>.trim()
מסיר רווחים מהמחרוזת המקורית. הוספת הערה לשיטה עם @CheckResult
מסמנת שימוש ב-<String>.trim()
שבו מבצע הקריאה לא עושה דבר עם הערך המוחזר של השיטה.
בדוגמה הבאה מתווספת הערה לשיטה checkPermissions()
כדי לבדוק אם יש למעשה הפניה לערך המוחזר של השיטה. בנוסף, הוא מציין את השיטה enforcePermission()
בתור השיטה שצריך להציע למפתח כתחליף:
@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()
:
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
@CallSuper protected void onCreate(Bundle savedInstanceState) { }
הערות של טיפוס נתונים מוגדר מראש
הערות של טיפוס נתונים מותאם אישית בודקות אם פרמטר, ערך מוחזר או שדה מסוימים מפנים לקבוצה ספציפית של קבועים. הם גם מאפשרים להשלמת הקוד להציע באופן אוטומטי את הקבועים המותרים.
אפשר להשתמש בהערות @IntDef
ו-@StringDef
כדי ליצור הערות ממוספרות של קבוצות של מספרים שלמים ומחרוזות, כדי לאמת סוגים אחרים של הפניות לקוד.
בהערות מסוג Typedef נעשה שימוש ב-@interface
כדי להצהיר על סוג ההערה החדש שמכיל את המספרים.
ההערות @IntDef
ו-@StringDef
, יחד עם הערה @Retention
, מוסיפות הערה להערה החדשה והן נחוצות להגדרת הסוג המנומר. ההערה @Retention(RetentionPolicy.SOURCE)
מורה למהדר שלא לאחסן את נתוני ההערות הממוספרים בקובץ .class
.
בדוגמה הבאה מוסבר איך יוצרים הערה שבודקת אם ערך שמוענק כפרמטר של שיטה מפנה לאחת הקבועות שהוגדרו:
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_
חוקיים:
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
, למשל מיחידת הידור אחרת.
@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 לצורכי פיתוח, אם אתם מתכוונים להשתמש בו למטרות בדיקה בלבד.