تحسين فحص الرمز باستخدام التعليقات التوضيحية

يمكن أن يساعدك استخدام أدوات فحص الرموز، مثل lint، في العثور على المشاكل وتحسين الرمز، ولكن لا يمكن لأدوات الفحص استنتاج الكثير من المعلومات. على سبيل المثال، تستخدم أرقام تعريف موارد Androidint لتحديد السلاسل والرسومات والألوان وأنواع الموارد الأخرى، لذلك لا يمكن لأدوات الفحص معرفة ما إذا كنت قد حدّدت مورد سلسلة في المكان الذي كان يجب فيه تحديد لون. يعني هذا الموقف أنّه قد يتم عرض تطبيقك بشكل غير صحيح أو قد يتعذّر تشغيله على الإطلاق، حتى إذا كنت تستخدم ميزة فحص الرموز البرمجية.

تتيح لك التعليقات التوضيحية تقديم تلميحات لأدوات فحص التعليمات البرمجية، مثل أداة Lint، للمساعدة في اكتشاف مشكلات التعليمات البرمجية الأكثر دقة. تتم إضافة التعليقات التوضيحية كعلامات بيانات وصفية تعلقها بالمتغيّرات والاقتباسات والقيم المعروضة لفحص القيم المعروضة للطريقة والمَعلمات التي تم تمريرها والمتغيّرات المحلية والاقتباسات والحقول. عند استخدام التعليقات التوضيحية مع أدوات فحص الرموز البرمجية، يمكن أن تساعدك في رصد مشاكل مثل استثناءات مؤشر الفراغ وحالات تعارض نوع المورد.

يتيح Android مجموعة متنوعة من التعليقات التوضيحية من خلال مكتبة التعليقات التوضيحية في Jetpack. يمكنك الوصول إلى المكتبة من خلال حزمة androidx.annotation.

ملاحظة: إذا كانت الوحدة تعتمد على معالج التعليقات التوضيحية، عليك استخدام إعدادات الاعتماد kapt أو ksp لـ Kotlin أو إعدادات الاعتماد annotationProcessor لـ Java لإضافة هذا الاعتماد.

إضافة تعليقات توضيحية إلى مشروعك

لتفعيل التعليقات التوضيحية في مشروعك، أضِف التبعية androidx.annotation:annotation إلى مكتبتك أو تطبيقك. ويتم التحقّق من أي تعليقات توضيحية تضيفها عند تنفيذ فحص код أو مهمة lint.

إضافة التبعية لـ Jetpack Annotations library

يتم نشر مكتبة Jetpack Annotations على مستودع Maven من Google. لإضافة مكتبة Jetpack Anotations إلى مشروعك، أدرِج السطر التالي في كتلة dependencies من ملف build.gradle أوملف build.gradle.kts:

Kotlinرائع

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

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

وبعد ذلك، انقر على المزامنة الآن في شريط الأدوات أو إشعار المزامنة الذي يظهر.

إذا كنت تستخدم تعليقات توضيحية في وحدة مكتبتك، يتم تضمين التعليقات التوضيحية كجزء من ملف annotations.zip بتنسيق XML ضمن ملف ملف أرشيف Android (AAR). لا تؤدي إضافة تبعية androidx.annotation إلى تقديم اعتمادية لأي مستخدمين في مرحلة ما بعد الإنتاج في مكتبتك.

ملاحظة: إذا كنت تستخدم مكتبات Jetpack الأخرى، قد لا تحتاج إلى إضافة الاعتمادية androidx.annotation. بما أنّ العديد من مكتبات Jetpack الأخرى تعتمد على مكتبة التعليقات التوضيحية، قد يكون بإمكانك الوصول إلى التعليقات التوضيحية.

للحصول على قائمة كاملة بالتعليقات التوضيحية المضمّنة في مستودع Jetpack، يمكنك الاطّلاع على مرجع مكتبة التعليقات التوضيحية في Jetpack أو استخدام ميزة الإكمال التلقائي لعرض الخيارات المتاحة لعبارة import androidx.annotation..

إجراء عمليات فحص للرموز البرمجية

لبدء فحص الرمز من Android Studio، والذي يتضمّن التحقّق من التعليقات التوضيحية وفحص lint التلقائي، اختَر تحليل > فحص الرمز من الجدول. يعرض Android Studio رسائل تعارض لرصد المشاكل المحتمَلة التي يتعارض فيها الرمز البرمجي مع التعليقات التوضيحية واقتراح حلول محتملة.

يمكنك أيضًا فرض التعليقات التوضيحية من خلال تشغيل المهمة lint باستخدام سطر الأوامر. على الرغم من أنّ هذا قد يكون مفيدًا للإبلاغ عن المشاكل باستخدام خادم دمج مستمر، لا تفرض مهمة lint استخدام التعليقات التوضيحية للقيمة الخالية (الموضَّحة في القسم التالي)، بل ينفّذ Android Studio ذلك فقط. لمزيد من المعلومات عن تفعيل عمليات فحص lint وتنفيذها، اطّلِع على مقالة تحسين الرمز البرمجي باستخدام عمليات فحص lint.

على الرغم من أنّ تعارضات التعليقات التوضيحية تؤدي إلى ظهور تحذيرات، لا تمنع هذه التحذيرات compilingتطبيقك.

التعليقات التوضيحية للقيمة الخالية

يمكن أن تكون التعليقات التوضيحية حول القيمة الخالية مفيدة في رمز Java لفرض ما إذا كان يمكن أن تكون القيم خالية. وهي أقل فائدة في رمز Kotlin، لأنّ Kotlin تتضمّن قواعد إمكانية قبول القيم الفارغة التي يتم فرضها في وقت الترجمة.

أضِف التعليقَين التوضيحيَين @Nullable و @NonNull للتحقّق من قيمة فارغة لمتغيّر أو مَعلمة أو قيمة معروضة. تشير التعليق التوضيحي @Nullable إلى متغير أو معلَمة أو قيمة معروضة يمكن أن تكون فارغة. يشير الرمز @NonNull إلى متغيّر أو مَعلمة أو قيمة معروضة لا يمكن أن تكون فارغة.

على سبيل المثال، إذا تم تمرير متغيّر محلي يحتوي على قيمة فارغة كمَعلمة إلى طريقة مع إرفاق التعليق التوضيحي @NonNull بهذه المَعلمة، يؤدي إنشاء الرمز إلى توليد تحذير يشير إلى تعارض غير فارغ. بالإضافة إلى ذلك، يؤدي محاولة الإشارة إلى نتيجة طريقة تم وضع علامة @Nullable عليها بدون التحقّق أولاً مما إذا كانت النتيجة فارغة إلى توليد تحذير فارغ. لا تستخدم @Nullable إلا مع القيمة المعروضة لطريقة ما إذا كان يجب تحديد قيمة فارغة في كل استخدام لهذه الطريقة بشكل صريح.

يوضّح المثال التالي حالة عدم السماح بالقيمة الخالية. لا يستفيد نموذج رمز Kotlin من التعليق التوضيحي @NonNull لأنّه تتم إضافته تلقائيًا إلى الرمز الثنائي الذي تم إنشاؤه عند تحديد نوع غير قابل للقيمة الخالية. يستفيد مثال Java من التعليق التوضيحي @NonNull على المَعلمتَين context وattrs للتحقّق من أنّ قيم المَعلمات المُرسَلة ليست فارغة. وتتحقّق أيضًا من أنّ الطريقة onCreateView() نفسها لا تعرض قيمة فارغة:

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" إجراء تحليل للقيم الفارغة لاستنتاج تعليقات توضيحية للقيم الفارغة وإدراجها في الرمز البرمجي تلقائيًا. يفحص تحليل قابلية العدم العقود في جميع التسلسلات الهرمية للطرق في الرمز البرمجي لرصد ما يلي:

• استدعاء طرق يمكنها عرض قيمة فارغة
• الطرق التي يجب ألا تُعرِض قيمة فارغة
• المتغيّرات، مثل الحقول والمتغيّرات المحلية والمعلَمات التي يمكن أن تكون فارغة.
• المتغيّرات، مثل الحقول والمتغيّرات المحلية والمَعلمات، التي لا يمكنها احتواء قيمة فارغة

بعد ذلك، يُدرج التحليل تلقائيًا التعليقات التوضيحية المناسبة للقيم الخالية في المواقع الجغرافية التي تم رصدها.

لإجراء تحليل القيم الفارغة في "استوديو Android"، انقر على تحليل > استنتاج القيم الفارغة. يُدرج Android Studio التعليقَين التوضيحيَين @Nullable و@NonNull في Android في المواقع التي تم رصدها في الرمز البرمجي. بعد إجراء تحليل فارغ، من المستحسن التحقق من التعليقات التوضيحية التي تم إدخالها.

ملاحظة: عند إضافة تعليقات توضيحية عن القيم الخالية، قد يقترح خيار الإكمال التلقائي تعليقات توضيحية IntelliJ @Nullable و @NotNull بدلاً من تعليقات توضيحية Android عن القيم الخالية وقد يستورد تلقائيًا المكتبة المقابلة. ومع ذلك، لا يبحث مدقّق الأخطاء lint في "استوديو Android" سوى عن التعليقات التوضيحية للقيم الخالية في Android. عند التحقّق من التعليقات التوضيحية ، تأكَّد من أنّ مشروعك يستخدم التعليقات التوضيحية للقيم الخالية في Android حتى يتمكّن فحص lint من إعلامك بشكل صحيح أثناء فحص الرمز.

التعليقات التوضيحية للمراجع

يمكن أن يكون التحقّق من أنواع الموارد مفيدًا لأنّ نظام التشغيل 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 لتحديد أنّ المَعلمة يجب أن تكون عددًا صحيحًا للون. ستُبلغ أدوات الإنشاء عن الرمز غير الصحيح الذي يُمرِّر معرّف مورد لون مثل android.R.color.black بدلاً من عدد صحيح للّون إلى الطرق المُشارَك فيها تعليقات توضيحية.

التعليقات التوضيحية لسلسلة المحادثات

تتحقّق التعليقات التوضيحية لسلسلة المحادثات ممّا إذا تم استدعاء طريقة من نوع معيّن من سلسلة محادثات. يمكن استخدام التعليقات التوضيحية التالية في السلسلة:

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

تتعامل أدوات الإنشاء مع التعليقات التوضيحية @MainThread و @UiThread على أنّها قابلة للتبديل، لذا يمكنك استدعاء طرق @UiThread من طرق @MainThread والعكس صحيح. ومع ذلك، من الممكن أن يختلف مؤشر تسلسل واجهة المستخدم عن مؤشر التسلسل الرئيسي، في حال تطبيقات النظام التي تتضمّن طرق عرض متعددة على مؤشرات تسلسل مختلفة. وبالتالي، يجب إضافة تعليقات توضيحية إلى الطرق المرتبطة بالعرض الهرمي للتطبيق من خلال @UiThread وإضافة تعليقات توضيحية إلى الطرق المرتبطة بدورة حياة التطبيق فقط من خلال @MainThread.

إذا كانت جميع الطرق في فئة تتشارك متطلبات المعالجة المتعدّدة ال threads نفسها، يمكنك إضافة تعليق توضيحي واحد لسلسلة رسائل إلى الفئة للتحقّق من أنّه يتم استدعاء جميع الطرق في الفئة من النوع نفسه من سلسلة الرسائل.

من الاستخدامات الشائعة للتعليقات التوضيحية للخيوط هي التحقّق من أنّ الطرق أو الفئات التي تمّت إضافة تعليق توضيحي إليها باستخدام @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 مما إذا كانت قيمة المَعلمة المتغيرة أو المَعلمة المتغيرة المزدوجة ضمن نطاق محدّد من قيم النقطة العائمة. يشير المثال التالي إلى أنّ مَعلمة alpha يجب أن تحتوي على قيمة عائمة تتراوح بين 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() للإشارة إلى أنّه يجب أن يكون لدى المُرسِل للإجراء إذن 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;

يتطلّب المثال التالي أن يكون لدى المُرسِل لطريقة 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");

الأذونات غير المباشرة

عندما يعتمد أحد الأذونات على القيمة المحدّدة التي يتم تقديمها إلى مَعلمة إحدى الطرق، استخدِم @RequiresPermission على المَعلمة نفسها بدون إدراج الأذونات المحدّدة. على سبيل المثال، تستخدم الطريقة startActivity(Intent) إذنًا غير مباشر على النية التي تم تمريرها إلى الطريقة:

KotlinJava

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

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

عند استخدام الأذونات غير المباشرة، تُجري أدوات الإنشاء تحليلًا لتدفّق البيانات للتحقّق مما إذا كانت العبارة التي تم تمريرها إلى الطريقة تحتوي على أي تعليقات توضيحية @RequiresPermission. وبعد ذلك، تفرض أي تعليقات توضيحية حالية من المَعلمة على الطريقة نفسها. في مثال startActivity(Intent)، تتسبب التعليقات التوضيحية في الفئة Intent في ظهور التحذيرات الناتجة عن الاستخدامات غير الصالحة لـ startActivity(Intent) عند تمرير إجراء إلى الطريقة بدون الحصول على الأذونات المناسبة كما هو موضّح في الشكل 1.

الشكل 1. التحذير الذي تم إنشاؤه من تعليق توضيحي غير مباشر للأذونات في طريقة startActivity(Intent)

تنشئ أدوات الإنشاء التحذير بشأن startActivity(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 بـ @RequiresPermission.Read أو @RequiresPermission.Write عند إضافة تعليقات توضيحية إلى معلَمة طريقة ما. ومع ذلك، بالنسبة إلى الأذونات غير المباشرة، يجب عدم استخدام @RequiresPermission مع التعليقات التوضيحية لأذونات القراءة أو الكتابة.

التعليقات التوضيحية للقيمة المعروضة

استخدِم التعليق التوضيحي @CheckResult لتأكيد استخدام نتيجة الطريقة أو القيمة المعروضة. بدلاً من إضافة التعليق التوضيحي @CheckResult إلى كل @CheckResultطريقة غير فارغة، أضِف التعليق التوضيحي لتوضيح نتائج @CheckResultالطرق التي قد تكون مربكة.

على سبيل المثال، غالبًا ما يظن مطوّرو Java الجدد عن طريق الخطأ أنّ <String>.trim() يزيل المسافات البيضاء من السلسلة الأصلية. إن التعليق التوضيحي على الطريقة باستخدام علامات @CheckResult يستخدم <String>.trim() حيث لا يفعل المتصل أي شيء بالقيمة التي تعرضها الطريقة.

يضيف المثال التالي تعليقات توضيحية إلى الطريقة checkPermissions() للتحقّق مما إذا كانت القيمة المعروضة للطريقة مُشار إليها فعليًا. ويُشير أيضًا إلى enforcePermission() method كطريقة يمكن أن نقترحها على المطوّر كبديل:

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() تُطلِق super.onCreate():

KotlinJava

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

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

التعليقات التوضيحية لأنواع البيانات

تتحقّق التعليقات التوضيحية لنوع البيانات من ما إذا كانت مَعلمة معيّنة أو قيمة معروضة أو حقل معيّن يشير إلى مجموعة معيّنة من الثوابت. وتتيح أيضًا إكمال الرموز البرمجية من أجل تقديم الثوابت المسموح بها تلقائيًا.

استخدِم التعليقات التوضيحية @IntDef و @StringDef لإنشاء تعليقات توضيحية مُدرَجة لمجموعات الأعداد الصحيحة والسلاسل من أجل التحقّق من صحة أنواع أخرى من مراجع الرموز البرمجية.

تستخدِم التعليقات التوضيحية لأنواع البيانات @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 عدم إزالة فئة أو طريقة تمّت إضافة تعليق توضيحي إليها عند تصغير الرمز المبرمَج في وقت الإنشاء. تتم عادةً إضافة هذا التعليق التوضيحي إلى الطرق والفئات التي يتم الوصول إليها من خلال ميزة "الاستكشاف" لمنع المُجمِّع من التعامل مع الرمز البرمجي على أنّه غير مستخدَم.

تنبيه: إنّ الفئات والطرق التي تضيف إليها تعليقات توضيحية باستخدام @Keep تظهر دائمًا في حزمة APK الخاصة بتطبيقك، حتى إذا لم تُشِر أبدًا إلى هذه الفئات والطرق ضمن منطق تطبيقك.

للحفاظ على حجم تطبيقك صغيرًا، ننصحك بالتفكير في ما إذا كان من الضروري الاحتفاظ بكل تعليق توضيحي @Keep في تطبيقك. إذا كنت تستخدِم ميزة "الاستدلال" لمحاولة الوصول إلى فئة أو طريقة مُشارَك فيها تعليق توضيحي، استخدِم شرطًا من نوع -if في قواعد ProGuard، مع تحديد الفئة التي تُجري طلبات الاستدلال.

لمزيد من المعلومات حول كيفية تصغير الرمز البرمجي وتحديد الرمز الذي لا تتم إزالته، اطّلِع على مقالة تصغير حجم تطبيقك وإخفاء مفاتيح فك التشفير وتحسينه.

التعليقات التوضيحية لمستوى عرض الرمز

استخدِم التعليقات التوضيحية التالية للإشارة إلى مستوى ظهور أجزاء معيّنة من الرمز البرمجي، مثل methods أو classes أو fields أو packages.

إظهار الرمز البرمجي للاختبار

تشير @VisibleForTesting أنّ الطريقة التي تتضمّن تعليقات توضيحية تكون مرئية أكثر من اللازم عادةً لجعل الطريقة قابلة للاختبار. يحتوي هذا التعليق التوضيحي على وسيطة otherwise اختيارية تتيح لك تحديد مستوى إذن الوصول إلى الطريقة في حال عدم الحاجة إلى جعله متاحًا للاختبار. يستخدم Lint الوسيطة otherwise لفرض مستوى العرض المقصود.

في المثال التالي، تكون قيمة myMethod() عادةً private، ولكنّها package-private للاختبارات. باستخدام التصنيف VisibleForTesting.PRIVATE ، يعرض lint رسالة إذا تم استدعاء هذه الطريقة من خارج سياق الوصول المسموح به من خلال private، مثل وحدة تجميع مختلفة.

KotlinJava

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

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

يمكنك أيضًا تحديد @VisibleForTesting(otherwise = VisibleForTesting.NONE) للإشارة إلى أنّ طريقة الاختبار تتوفّر فقط للاختبار. هذا النموذج هو نفسه المستخدَم في @RestrictTo(TESTS). كلتاهما تُجريان فحص الوبر نفسه.

حظر واجهة برمجة تطبيقات

يشير التعليق التوضيحي @RestrictTo إلى أنّ إمكانية الوصول إلى واجهة برمجة التطبيقات التي تتضمّن تعليقات توضيحية (الحزمة أو الفئة أو الطريقة) محدود، على النحو التالي:

الفئات الفرعية

استخدِم نموذج التعليق التوضيحي @RestrictTo(RestrictTo.Scope.SUBCLASSES) لحصر الوصول إلى واجهة برمجة التطبيقات على الفئات الفرعية فقط.

لا يمكن الوصول إلى واجهة برمجة التطبيقات هذه إلا من خلال الصفوف التي تمديدها من الصف المُشارَك. لا يكون معدِّل Java protected تقييديًا بما يكفي، لأنّه يسمح بالوصول من فئات غير ذات صلة ضمن الحزمة نفسها. هناك أيضًا حالات تريد فيها ترك public public لتوفير المرونة في المستقبل، لأنّه لا يمكنك أبدًا إنشاء public protected تم تجاوزه سابقًا، ولكنك تريد تقديم تلميح مفاده أنّ الفئة مخصّصة للاستخدامات داخل الفئة أو من الفئات الفرعية فقط.

المكتبات

استخدِم نموذج التعليق التوضيحي @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) لمحاولة حظر الوصول إلى واجهة برمجة التطبيقات على مكتباتك فقط.

ويمكن لرمز المكتبة فقط الوصول إلى واجهة برمجة التطبيقات التي تتضمّن تعليقات توضيحية. يتيح لك ذلك ليس فقط تنظيم رموذك في أي تسلسل هرمي للحزمة تريده، بل يتيح لك أيضًا مشاركة الرمز بين مجموعة من المكتبات ذات الصلة. يتوفّر هذا الخيار حاليًا لمكتبات Jetpack التي تحتوي على الكثير من رموز التنفيذ غير المخصّصة للاستخدام الخارجي، ولكن يجب أن تكون public لمشاركتها في مكتبات Jetpack التكميلية المختلفة.

الاختبار

استخدِم نموذج التعليق التوضيحي @RestrictTo(RestrictTo.Scope.TESTS) لمنع المطوّرين الآخرين من الوصول إلى واجهات برمجة التطبيقات المخصّصة للاختبار.

لا يمكن سوى لرمز الاختبار الوصول إلى واجهة برمجة التطبيقات التي تمت عليها تعليقات توضيحية. يمنع ذلك المطوّرين الآخرين من استخدام واجهات برمجة التطبيقات المخصّصة لأغراض الاختبار فقط.