Ek açıklamalar ile kod incelemesini iyileştirme

Lint gibi kod inceleme araçlarını kullanmak sorunları bulmanıza ve kodunuzu iyileştirmenize yardımcı olabilir ancak inceleme araçları yalnızca belirli bir noktaya kadar çıkarım yapabilir. Android kaynak kimlikleri. Örneğin, dizeleri, grafikleri, renkleri ve diğer kaynak türlerini tanımlamak için int kullanılır. Bu nedenle, inceleme araçları, renk belirtmeniz gereken yerde bir dize kaynağı belirtip belirtmediğinizi anlayamaz. Bu durum, kod incelemesi kullansanız bile uygulamanızın yanlış şekilde oluşturulabileceği veya hiç çalışmayabileceği anlamına gelir.

Açıklamalar, bu daha ince kod sorunlarının tespit edilmesine yardımcı olmak için lint gibi kod inceleme araçlarına ipuçları vermenizi sağlar. Açıklamalar, yöntem dönüş değerlerini, iletilen parametreleri, yerel değişkenleri ve alanları incelemek için değişkenlere, parametrelere ve dönüş değerlerine eklediğiniz meta veri etiketleri olarak eklenir. Açıklamalar, kod inceleme araçlarıyla birlikte kullanıldığında null işaretçi istisnaları ve kaynak türü çakışmaları gibi sorunları tespit etmenize yardımcı olabilir.

Android, Jetpack Annotations Library aracılığıyla çeşitli ek açıklamaları destekler. Kitaplığa androidx.annotation paketinden erişebilirsiniz.

Not: Bir modülün ek açıklama işlemcisine bağımlılığı varsa bu bağımlılığı eklemek için Kotlin'de kapt veya ksp bağımlılık yapılandırmasını, Java'da ise annotationProcessor bağımlılık yapılandırmasını kullanmanız gerekir.

Projenize ek açıklamalar ekleme

Projenizde ek açıklamaları etkinleştirmek için kitaplığınıza veya uygulamanıza androidx.annotation:annotation bağımlılığını ekleyin. Eklediğiniz tüm ek açıklamalar, kod incelemesi veya lint görevini çalıştırdığınızda kontrol edilir.

Jetpack Annotations kitaplığı bağımlılığını ekleme

Jetpack Annotations kitaplığı, Google'ın Maven deposunda yayınlanır. Jetpack Anotations kitaplığını projenize eklemek için build.gradle veya build.gradle.kts dosyanızın dependencies bloğuna aşağıdaki satırı ekleyin:

Kotlin

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

Groovy

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

Ardından, gösterilen araç çubuğunda veya senkronizasyon bildiriminde Şimdi Senkronize Et'i tıklayın.

Kendi kitaplık modülünüzde ek açıklamalar kullanıyorsanız ek açıklamalar, annotations.zip dosyasında XML biçiminde Android Arşivi (AAR) yapıtının bir parçası olarak eklenir. androidx.annotation bağımlılığının eklenmesi, kitaplığınızın aşağı akış kullanıcıları için herhangi bir bağımlılık oluşturmaz.

Not: Diğer Jetpack kitaplıklarını kullanıyorsanız androidx.annotation bağımlılığını eklemeniz gerekmeyebilir. Diğer birçok Jetpack kitaplığı, Annotations Library'ye bağlı olduğundan, ek açıklamalara erişiminiz olabilir.

Jetpack deposunda bulunan ek açıklamaların tam listesi için Jetpack Annotations kitaplığı referansına bakın veya import androidx.annotation. ifadesi için kullanılabilir seçenekleri görüntülemek üzere otomatik tamamlama özelliğini kullanın.

Kod incelemelerini çalıştırma

Android Studio'dan kod incelemesi başlatmak için (ek açıklamaları doğrulama ve otomatik lint kontrolü dahil) menüden Analyze > Inspect Code'u (Analiz Et > Kodu İncele) seçin. Android Studio, kodunuzun ek açıklamalarla çakıştığı yerlerde olası sorunları işaretlemek ve olası çözümleri önermek için çakışma mesajları gösterir.

Ayrıca, komut satırını kullanarak lint görevini çalıştırarak ek açıklamaları zorunlu kılabilirsiniz. Bu, sürekli entegrasyon sunucusuyla ilgili sorunları işaretlemek için yararlı olsa da lint görevi, nullness ek açıklamalarını (sonraki bölümde açıklanmıştır) zorunlu kılmaz. Bunu yalnızca Android Studio yapar. Lint incelemelerini etkinleştirme ve çalıştırma hakkında daha fazla bilgi için Lint kontrolleriyle kodunuzu iyileştirme başlıklı makaleyi inceleyin.

Açıklama çakışmaları uyarı oluşturmasına rağmen bu uyarılar uygulamanızın derlenmesini engellemez.

Nullness ek açıklamaları

Değerlerin null olup olamayacağını zorunlu kılmak için Java kodunda nullness ek açıklamaları yararlı olabilir. Kotlin'de derleme zamanında zorunlu kılınan yerleşik nullability kuralları olduğundan bu tür açıklamalar Kotlin kodunda daha az kullanışlıdır.

Belirli bir değişkenin, parametrenin veya dönüş değerinin boş olup olmadığını kontrol etmek için @Nullable ve @NonNull ek açıklamalarını ekleyin. @Nullable notu, boş olabilen bir değişkeni, parametreyi veya dönüş değerini gösterir. @NonNull, boş olamayan bir değişkeni, parametreyi veya dönüş değerini gösterir.

Örneğin, boş değer içeren bir yerel değişken, parametresine @NonNull ek açıklaması eklenmiş bir yönteme parametre olarak iletilirse kod oluşturulurken boş olmayan bir çakışmayı belirten bir uyarı oluşturulur. Ayrıca, @Nullable ile işaretlenmiş bir yöntemin sonucuna başvurmadan önce sonucun boş olup olmadığını kontrol etmeye çalışmak da boşluk uyarısı oluşturur. Yalnızca yöntemin her kullanımında açıkça null kontrolü yapılması gerekiyorsa yöntemin dönüş değerinde @Nullable kullanın.

Aşağıdaki örnekte, null değer atanabilirliğin nasıl kullanıldığı gösterilmektedir. Kotlin örnek kodu, @NonNull ek açıklamasını kullanmaz. Bunun nedeni, boş değer atanamayan bir tür belirtildiğinde bu ek açıklamanın oluşturulan bayt koduna otomatik olarak eklenmesidir. Java örneğinde, iletilen parametre değerlerinin boş olup olmadığını kontrol etmek için context ve attrs parametrelerinde @NonNull ek açıklaması kullanılır. Ayrıca, onCreateView() yönteminin kendisinin null döndürmediğini de kontrol eder:

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) {
      ...
      }
...

Boş değer atanabilirliği analizi

Android Studio, kodunuzdaki nullness ek açıklamalarını otomatik olarak tahmin etmek ve eklemek için nullability analizi çalıştırmayı destekler. Nullability analizi, kodunuzdaki yöntem hiyerarşilerinde bulunan sözleşmeleri tarayarak şunları tespit eder:

• Boş değer döndürebilen çağırma yöntemleri.
• Null değeri döndürmemesi gereken yöntemler.
• Alanlar, yerel değişkenler ve parametreler gibi boş değerli olabilen değişkenler.
• Alanlar, yerel değişkenler ve parametreler gibi boş değer içermeyen değişkenler.

Ardından analiz, algılanan konumlara uygun boşluk ek açıklamalarını otomatik olarak ekler.

Android Studio'da nullability analizi çalıştırmak için Analyze (Analiz Et) > Infer Nullity (Nullability'i Çıkar) seçeneğini belirleyin. Android Studio, kodunuzdaki algılanan konumlara Android @Nullable ve @NonNull ek açıklamalarını ekler. Boş analiz yaptıktan sonra eklenen ek açıklamaları doğrulamanız önerilir.

Not: Boşlukla ilgili ek açıklamalar eklerken otomatik tamamlama, Android boşluk ek açıklamaları yerine IntelliJ @Nullable ve @NotNull ek açıklamalarını önerebilir ve ilgili kitaplığı otomatik olarak içe aktarabilir. Ancak Android Studio hata analizi denetleyicisi yalnızca Android null ek açıklamalarını arar. Açıklamalarınızı doğrularken projenizin Android null açıklamalarını kullandığını onaylayın. Böylece lint denetleyicisi, kod incelemesi sırasında sizi uygun şekilde bilgilendirebilir.

Kaynak ek açıklamaları

Android'in drawable ve string kaynakları gibi kaynaklara yaptığı referanslar tam sayı olarak iletildiğinden kaynak türlerini doğrulamak yararlı olabilir.

Bir parametrenin String gibi belirli bir kaynak türüne referans vermesini bekleyen kod, int'nin beklenen referans türüne iletilebilir ancak aslında R.string kaynağı gibi farklı bir kaynak türüne referans verebilir.

Örneğin, bir kaynak parametresinin R.string referansı içerip içermediğini kontrol etmek için @StringRes ek açıklamaları ekleyin.

Kotlin

abstract fun setTitle(@StringRes resId: Int)

Java

public abstract void setTitle(@StringRes int resId)

Kod incelemesi sırasında, parametreye bir R.string referansı geçirilmezse ek açıklama uyarı oluşturur.

@DrawableRes, @DimenRes, @ColorRes ve @InterpolatorRes gibi diğer kaynak türleri için ek açıklamalar aynı ek açıklama biçimi kullanılarak eklenebilir ve kod incelemesi sırasında çalıştırılabilir.

Parametreniz birden fazla kaynak türünü destekliyorsa belirli bir parametreye birden fazla kaynak türü açıklaması ekleyebilirsiniz. Açıklama eklenen parametrenin herhangi bir türde R kaynak olabileceğini belirtmek için @AnyRes kullanın.

Bir parametrenin renk kaynağı olması gerektiğini belirtmek için @ColorRes kullanabilirsiniz ancak RRGGBB veya AARRGGBB biçimindeki bir renk tamsayısı, renk kaynağı olarak tanınmaz. Bunun yerine, bir parametrenin renk tam sayısı olması gerektiğini belirtmek için @ColorInt ek açıklamasını kullanın. Derleme araçları, açıklama eklenmiş yöntemlere renk tamsayısı yerine android.R.color.black gibi bir renk kaynağı kimliği ileten yanlış kodu işaretler.

İleti dizisi ek açıklamaları

İş parçacığı ek açıklamaları, bir yöntemin belirli bir tür iş parçacığından çağrılıp çağrılmadığını kontrol eder. Aşağıdaki ileti dizisi ek açıklamaları desteklenir:

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

Derleme araçları, @MainThread ve @UiThread ek açıklamalarını birbirinin yerine kullanılabilir olarak değerlendirir. Bu nedenle, @UiThread yöntemlerini @MainThread yöntemlerinden, @MainThread yöntemlerini de @UiThread yöntemlerinden çağırabilirsiniz. Ancak farklı iş parçacıklarında birden fazla görünümü olan sistem uygulamalarında bir kullanıcı arayüzü iş parçacığının ana iş parçacığından farklı olması mümkündür. Bu nedenle, bir uygulamanın görünüm hiyerarşisiyle ilişkili yöntemleri @UiThread ile, yalnızca bir uygulamanın yaşam döngüsüyle ilişkili yöntemleri ise @MainThread ile açıklama eklemeniz gerekir.

Bir sınıftaki tüm yöntemler aynı iş parçacığı gereksinimini paylaşıyorsa sınıfa tek bir iş parçacığı ek açıklaması ekleyerek sınıftaki tüm yöntemlerin aynı tür iş parçacığından çağrıldığını doğrulayabilirsiniz.

İş parçacığı ek açıklamalarının yaygın bir kullanımı, @WorkerThread ile ek açıklama eklenmiş yöntemlerin veya sınıfların yalnızca uygun bir arka plan iş parçacığından çağrıldığını doğrulamaktır.

Değer sınırlaması ek açıklamaları

Geçirilen parametrelerin değerlerini doğrulamak için @IntRange, @FloatRange ve @Size ek açıklamalarını kullanın. Hem @IntRange hem de @FloatRange, kullanıcıların aralığı yanlış girme olasılığının yüksek olduğu parametrelere uygulandığında en iyi sonucu verir.

@IntRange notu, bir tam sayı veya uzun parametre değerinin belirtilen aralıkta olduğunu doğrular. Aşağıdaki örnek, alpha parametresinin 0 ile 255 arasında bir tam sayı değeri içermesi gerektiğini gösteriyor:

Kotlin

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

Java

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

@FloatRange açıklaması, kayan veya çift parametre değerinin belirtilen kayan nokta değerleri aralığında olup olmadığını kontrol eder. Aşağıdaki örnek, alpha parametresinin 0,0 ile 1,0 arasında bir kayan nokta değeri içermesi gerektiğini gösterir:

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 açıklaması, bir koleksiyonun veya dizinin boyutunu ya da bir dizenin uzunluğunu kontrol eder. @Size ek açıklaması, aşağıdaki nitelikleri doğrulamak için kullanılabilir:

• Minimum boyut (ör. @Size(min=2))
• Maksimum boyut (ör. @Size(max=2))
• Kesin boyut (ör. @Size(2))
• Boyutun katı olması gereken bir sayı (ör. @Size(multiple=2))

Örneğin, @Size(min=1) bir koleksiyonun boş olup olmadığını kontrol eder ve @Size(3) bir dizinin tam olarak üç değer içerdiğini doğrular.

Aşağıdaki örnekte, location dizisinin en az bir öğe içermesi gerektiği belirtilmektedir:

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);
}

İzin ek açıklamaları

Bir yöntemin arayanının izinlerini doğrulamak için @RequiresPermission ek açıklamasını kullanın. Geçerli izinler listesinden tek bir izni kontrol etmek için anyOf özelliğini kullanın. Bir izin grubunu kontrol etmek için allOf özelliğini kullanın. Aşağıdaki örnekte, yöntemi çağıranın permission.SET_WALLPAPERS iznine sahip olması gerektiğini belirtmek için setWallpaper() yöntemi açıklama eklenerek gösterilmektedir:

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;

Aşağıdaki örnekte, copyImageFile() yöntemini çağıranın hem harici depolama alanına okuma erişimi hem de kopyalanan resimdeki konum meta verilerine okuma erişimi olması gerekir:

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) {
    //...
}

Niyetlerle ilgili izinler için izin şartını, niyetin işlem adını tanımlayan dize alanına yerleştirin:

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";

Okuma ve yazma erişimi için ayrı izinler gerektiren içerik sağlayıcılarla ilgili izinlerde her izin şartını @RequiresPermission.Read veya @RequiresPermission.Write ek açıklamasıyla sarmalayın:

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");

Dolaylı izinler

Bir izin, yöntemin parametresine sağlanan değere bağlı olduğunda belirli izinleri listelemeden parametrenin kendisinde @RequiresPermission kullanın. Örneğin, startActivity(Intent) yöntemi, yönteme iletilen amaç üzerinde dolaylı bir izin kullanır:

Kotlin

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

Java

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

Dolaylı izinleri kullandığınızda derleme araçları, yönteme iletilen bağımsız değişkenin @RequiresPermission ek açıklamaları içerip içermediğini kontrol etmek için veri akışı analizi gerçekleştirir. Ardından, parametredeki mevcut ek açıklamaları yöntemde zorunlu kılar. startActivity(Intent) örneğinde, Intent sınıfındaki ek açıklamalar, Şekil 1'de gösterildiği gibi uygun izinlere sahip olmayan bir amaç yönteme iletildiğinde startActivity(Intent)'nın geçersiz kullanımlarıyla ilgili uyarıların gösterilmesine neden olur.

1.şekil startActivity(Intent) yönteminde dolaylı izin notundan oluşturulan uyarı.

Derleme araçları, startActivity(Intent) sınıfındaki ilgili amaç işlemi adındaki nottan Intent üzerinde uyarı oluşturur:

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";

Gerekirse bir yöntemin parametresini açıklama eklerken @RequiresPermission yerine @RequiresPermission.Read veya @RequiresPermission.Write kullanabilirsiniz. Ancak dolaylı izinler için @RequiresPermission, okuma veya yazma izni ek açıklamalarıyla birlikte kullanılmamalıdır.

Döndürülen değer ek açıklamaları

Bir yöntemin sonucunun veya dönüş değerinin gerçekten kullanıldığını doğrulamak için @CheckResult ek açıklamasını kullanın. Boş olmayan her yöntemi @CheckResult ile açıklama eklemek yerine, kafa karıştırıcı olabilecek yöntemlerin sonuçlarını netleştirmek için açıklama ekleyin.

Örneğin, yeni Java geliştiricileri genellikle <String>.trim() ifadesinin orijinal dizedeki boşlukları kaldırdığını yanlışlıkla düşünür. Yöntemi @CheckResult ile açıklama eklemek, arayanın yöntemin döndürülen değeriyle hiçbir şey yapmadığı <String>.trim() kullanımlarını işaretler.

Aşağıdaki örnekte, yöntemin dönüş değerine gerçekten referans verilip verilmediğini kontrol etmek için checkPermissions() yöntemi açıklama eklenerek gösterilmektedir. Ayrıca, enforcePermission() yöntemini, geliştiriciye alternatif olarak önerilecek bir yöntem olarak adlandırır:

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 ek açıklamaları

Bir geçersiz kılma yönteminin, yöntemin üst uygulamasını çağırdığını doğrulamak için @CallSuper ek açıklamasını kullanın.

Aşağıdaki örnek, geçersiz kılınan yöntem uygulamalarının super.onCreate() yöntemini çağırmasını sağlamak için onCreate() yöntemini açıklama olarak ekler:

Kotlin

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

Java

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

Typedef ek açıklamaları

Typedef ek açıklamaları, belirli bir parametrenin, dönüş değerinin veya alanın belirli bir sabitler grubuna referans verip vermediğini kontrol eder. Ayrıca, izin verilen sabitleri otomatik olarak sunmak için kod tamamlamayı da etkinleştirirler.

Diğer kod referansı türlerini doğrulamak için tamsayı ve dize kümelerinin numaralandırılmış ek açıklamalarını oluşturmak üzere @IntDef ve @StringDef ek açıklamalarını kullanın.

Typedef ek açıklamaları, yeni numaralandırılmış ek açıklama türünü bildirmek için @interface kullanır. @IntDef ve @StringDef ek açıklamaları, @Retention ile birlikte yeni ek açıklamayı ekler ve numaralandırılmış türü tanımlamak için gereklidir. @Retention(RetentionPolicy.SOURCE) ek açıklaması, derleyiciye numaralandırılmış ek açıklama verilerini .class dosyasında depolamamasını söyler.

Aşağıdaki örnekte, yöntem parametresi olarak iletilen bir değerin tanımlanan sabitlerden birine referans verip vermediğini kontrol eden bir açıklama oluşturma adımları gösterilmektedir:

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);
}

Bu kodu oluşturduğunuzda, mode parametresi tanımlanmış sabitlerden (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST veya NAVIGATION_MODE_TABS) birine referans vermiyorsa uyarı oluşturulur.

Bir tam sayının belirli bir sabitler kümesi veya bir aralıktaki değer olabileceğini belirtmek için @IntDef ve @IntRange sembollerini birleştirin.

Sabitlerin işaretlerle birleştirilmesini etkinleştirme

Kullanıcılar izin verilen sabitleri bir işaretle (ör. |, &, ^ vb.) birleştirebiliyorsa bir parametrenin veya dönüş değerinin geçerli bir deseni referans alıp almadığını kontrol etmek için flag özelliğiyle bir ek açıklama tanımlayabilirsiniz.

Aşağıdaki örnekte, geçerli DISPLAY_ sabitlerinin listesini içeren DisplayOptions notu oluşturulmaktadır:

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 {}

...

Bir ek açıklama işaretiyle kod oluşturduğunuzda, süslenmiş parametre veya dönüş değeri geçerli bir kalıba referans vermiyorsa uyarı oluşturulur.

Ek açıklamayı tut

@Keep notu, derleme sırasında kod küçültülürken not eklenmiş bir sınıfın veya yöntemin kaldırılmamasını sağlar. Bu ek açıklama genellikle, derleyicinin kodu kullanılmamış olarak değerlendirmesini önlemek için yansıtma yoluyla erişilen yöntemlere ve sınıflara eklenir.

Dikkat: @Keep kullanarak ek açıklama eklediğiniz sınıflar ve yöntemler, uygulamanızın mantığında bu sınıflara ve yöntemlere hiçbir zaman referans vermeseniz bile uygulamanızın APK'sında her zaman görünür.

Uygulamanızın boyutunu küçük tutmak için uygulamanızdaki her @Keep ek açıklamasını korumanın gerekli olup olmadığını değerlendirin. Ek açıklamalı bir sınıfa veya yönteme erişmek için yansıtma kullanıyorsanız ProGuard kurallarınızda yansıtma çağrılarını yapan sınıfı belirten bir -if koşulu kullanın.

Kodunuzu küçültme ve hangi kodun kaldırılmayacağını belirtme hakkında daha fazla bilgi için Uygulamanızı küçültme, karartma ve optimize etme başlıklı makaleyi inceleyin.

Kod görünürlüğü notları

Metotlar, sınıflar, alanlar veya paketler gibi kodun belirli bölümlerinin görünürlüğünü belirtmek için aşağıdaki ek açıklamaları kullanın.

Test için kodu görünür hale getirme

@VisibleForTesting ek açıklaması, ek açıklama içeren bir yöntemin, yöntemin test edilebilir olması için normalde gerekenden daha görünür olduğunu gösterir. Bu ek açıklamada, test için görünür hale getirilmesi gerekmeseydi yöntemin görünürlüğünün ne olacağını belirlemenize olanak tanıyan isteğe bağlı bir otherwise bağımsız değişken bulunur. Lint, amaçlanan görünürlüğü zorunlu kılmak için otherwise bağımsız değişkenini kullanır.

Aşağıdaki örnekte, myMethod() normalde private'dir ancak testler için package-private'dir. VisibleForTesting.PRIVATE belirtmesiyle, bu yöntem private erişiminin izin verdiği bağlamın dışından (ör. farklı bir derleme biriminden) çağrılırsa lint bir mesaj gösterir.

Kotlin

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

Java

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

Bir yöntemin yalnızca test için kullanıldığını belirtmek üzere @VisibleForTesting(otherwise = VisibleForTesting.NONE) de belirtebilirsiniz. Bu form, @RestrictTo(TESTS) kullanmakla aynıdır. Her ikisi de aynı lint kontrolünü gerçekleştirir.

API'yi kısıtlama

@RestrictTo ek açıklaması, ek açıklama eklenen API'ye (paket, sınıf veya yöntem) erişimin aşağıdaki gibi sınırlı olduğunu gösterir:

Alt sınıflar

API erişimini yalnızca alt sınıflarla kısıtlamak için ek açıklama formunu @RestrictTo(RestrictTo.Scope.SUBCLASSES) kullanın.

Bu API'ye yalnızca açıklama eklenmiş sınıfı genişleten sınıflar erişebilir. Java'daki protected değiştiricisi, aynı paket içindeki alakasız sınıflardan erişime izin verdiği için yeterince kısıtlayıcı değildir. Ayrıca, daha önce public ve geçersiz kılınmış bir yöntemi public asla yapamayacağınız ancak sınıfın yalnızca sınıf içinde veya alt sınıflardan kullanılmak üzere tasarlandığına dair bir ipucu vermek istediğiniz için gelecekteki esneklik için bir yöntemi public bırakmak istediğiniz durumlar da vardır.protected

Kütüphaneler

Yalnızca kitaplıklarınıza API erişimini kısıtlamak için ek açıklama formunu @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) kullanın.

Yalnızca kitaplık kodunuz, açıklama eklenmiş API'ye erişebilir. Bu sayede kodunuzu istediğiniz paket hiyerarşisinde düzenleyebilir ve ilgili kitaplıklar arasında paylaşabilirsiniz. Bu seçenek, harici kullanım için tasarlanmamış ancak çeşitli tamamlayıcı Jetpack kitaplıklarında paylaşmak için public olması gereken çok sayıda uygulama kodu içeren Jetpack kitaplıklarında zaten kullanılabilir.

Test

Diğer geliştiricilerin test API'lerinize erişmesini önlemek için açıklama formunu @RestrictTo(RestrictTo.Scope.TESTS) kullanın.

Yalnızca test kodu, açıklama eklenmiş API'ye erişebilir. Bu sayede diğer geliştiricilerin, yalnızca test amaçlı kullanmayı planladığınız API'leri geliştirme için kullanması engellenir.