Ek açıklamalar ile kod incelemesini iyileştirme

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

Ek açıklamalar, daha ince kod sorunlarını tespit etmenize yardımcı olmak için lint gibi kod denetimi araçlarına ipucu vermenize olanak tanır. Ek açıklamalar, yöntem döndürme değerlerini, iletilen parametreleri, yerel değişkenleri ve alanları incelemek için değişkenlere, parametrelere ve döndürülen değerlere eklediğiniz meta veri etiketleri olarak eklenir. Kod inceleme araçlarıyla birlikte kullanıldığında ek açıklamalar, boş işaretçi istisnaları ve kaynak türü çakışmaları gibi sorunları tespit etmenize yardımcı olabilir.

Android, Jetpack Ek Açıklama Kitaplığı aracılığıyla çeşitli ek açıklamaları destekler. Kitaplığa androidx.annotation paketi aracılığıyla erişebilirsiniz.

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

Projenize ek açıklama ekleme

Projenizde ek açıklamaları etkinleştirmek için androidx.annotation:annotation bağımlılıklarını kitaplığınıza veya uygulamanıza ekleyin. Eklediğiniz tüm ek açıklamalar, kod denetimi veya lint görevi ç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, araç çubuğunda veya görünen senkronizasyon bildirimde Ş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ındaki XML biçimindeki Android Arşivi (AAR) yapısının bir parçası olarak dahil edilir. androidx.annotation bağımlılığını eklemek, kitaplığınızın yayındaki kullanıcıları için bağımlılığa neden olmaz.

Not: Diğer Jetpack kitaplıklarını kullanıyorsanız androidx.annotation bağımlılığını eklemeniz gerekmeyebilir. Diğer birçok Jetpack kitaplığı Ek Açıklama Kitaplığı'na bağlı olduğundan ek açıklamalara zaten erişiminiz olabilir.

Jetpack deposunda yer alan ek açıklamaların tam listesi için Jetpack Ek Açıklama kitaplığı referansına bakın veya import androidx.annotation. ifadesinde kullanılabilen seçenekleri görüntülemek için otomatik tamamlama özelliğini kullanın.

Kod denetimleri çalıştırma

Android Studio'dan, ek açıklamaları doğrulama ve otomatik lint kontrolü içeren bir kod incelemesi başlatmak için menüden Analiz > Kodu İncele'yi seçin. Android Studio, kodunuzun ek açıklamalarla çakıştığından kaynaklanan olası sorunları işaretlemek ve olası çözümler önermek için çakışma mesajları gösterir.

lint görevini komut satırını kullanarak çalıştırarak ek açıklamaları da zorunlu kılabilirsiniz. Bu, sürekli entegrasyon sunucusundaki sorunları işaretlemek için yararlı olsa da lint görevi, null notlarını (aşağıdaki bölümde açıklanmaktadır) zorunlu tutmaz. 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 bölümüne bakın.

Ek açıklama çakışmaları uyarı oluştursa da bu uyarılar uygulamanızın derlemesini engellemez.

Boşluk ek açıklamaları

Nullness ek açıklamaları, Java kodunda değerlerin boş olup olamayacağını uygulamak açısından yararlı olabilir. Kotlin, derleme zamanında uygulanan yerleşik boşluk kabul edilebilirlik kurallarına sahip olduğundan bu tür kontroller Kotlin kodunda daha az kullanışlıdır.

Belirli bir değişkenin, parametrenin veya döndürülen değerin boş olup olmadığını kontrol etmek için @Nullable ve @NonNull ek açıklamaları ekleyin. @Nullable ek açıklaması, boş olabilen bir değişkeni, parametreyi veya döndürülen değeri belirtir. @NonNull, null olamaz bir değişkeni, parametreyi veya döndürülen değeri gösterir.

Örneğin, null değer içeren bir yerel değişken, @NonNull ek açıklamasıyla birlikte bir yönteme parametre olarak iletilirse kod derlenirken null olmayan bir çakışma olduğunu belirten bir uyarı oluşturulur. Ayrıca, sonucun boş olup olmadığını kontrol etmeden @Nullable tarafından işaretlenen bir yöntemin sonucuna referansta bulunmaya çalışmak, boşluk uyarısı oluşturur. @Nullable değerini yalnızca yöntemin her kullanımının açıkça null olarak kontrol edilmesi gerekiyorsa yöntemin döndürdüğü değerde kullanın.

Aşağıdaki örnekte, boş değer özelliğinin nasıl kullanıldığı gösterilmektedir. Kotlin örnek kodunda, boş olmayan bir tür belirtildiğinde oluşturulan bayt koduna otomatik olarak eklendiği için @NonNull ek açıklamasından yararlanılmaz. Java örneğinde, iletilen parametre değerlerinin boş olmadığını kontrol etmek için context ve attrs parametrelerindeki @NonNull ek açıklamalarından yararlanılır. Ayrıca onCreateView() yönteminin kendisinin null döndürmediği de kontrol edilir:

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, kodunuzda boşluk olduğunu otomatik olarak tahmin edip boşluk ek açıklamaları eklemek için boşluk analizi çalıştırmayı destekler. Boş değer analizi, aşağıdakileri tespit etmek için kodunuzdaki yöntem hiyerarşileri genelinde sözleşmeleri tarar:

  • Boş değer döndürebilecek yöntemleri çağırma.
  • Null döndürmemesi gereken yöntemler.
  • Boş olabilecek alanlar, yerel değişkenler ve parametreler gibi değişkenler.
  • Alanlar, yerel değişkenler ve parametreler gibi boş değer tutamayan değişkenler.

Analiz, algılanan konumlara uygun null ek açıklamaları otomatik olarak ekler.

Android Studio'da boşluk analizi yapmak için Analizin > Boşluk Tahmini'ni seçin. Android Studio, kodunuzda algılanan konumlara Android @Nullable ve @NonNull ek açıklamalarını ekler. Boş analiz çalıştırdıktan sonra, eklenen ek açıklamaları doğrulamak iyi bir uygulamadır.

Not: Boşluk 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. Bununla birlikte, Android Studio lint denetleyicisi yalnızca Android null ek açıklamalarını arar. Ek açıklamalarınızı doğrularken, kod denetimi sırasında lint kontrol cihazının sizi doğru şekilde bilgilendirebilmesi için projenizin Android null ek açıklamalarını kullandığını onaylayın.

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.

Parametrenin belirli bir kaynak türüne (ör. String) başvurmasını bekleyen kod, beklenen int referans türüne iletilebilir. Ancak aslında R.string kaynağı gibi farklı bir kaynak türüne başvurabilir.

Ö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 denetimi sırasında, parametreye R.string referansı iletilmiyorsa ek açıklama bir 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 denetimi sırasında çalıştırılabilir.

Parametreniz birden fazla kaynak türünü destekliyorsa belirli bir parametreye birden fazla kaynak türü ek açıklaması ekleyebilirsiniz. Ek açıklamalı parametrenin herhangi bir R kaynağı türünde olabileceğini belirtmek için @AnyRes kullanın.

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

İleti dizisi ek açıklamaları

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

Derleme araçları, @MainThread ve @UiThread ek açıklamalarını birbirinin yerine kullanılabilir olarak değerlendirir. Bu nedenle, @MainThread yöntemlerinden @UiThread yöntemlerini ve bunun tam tersini çağırabilirsiniz. Ancak farklı iş parçalarında birden fazla görünüme sahip sistem uygulamaları söz konusu olduğunda, 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öntemlere @UiThread ile, yalnızca uygulamanın yaşam döngüsüyle ilişkili yöntemlere de @MainThread ile açıklama eklemeniz gerekir.

Bir sınıftaki tüm yöntemler aynı mesaj dizileri koşulunu paylaşıyorsa sınıftaki tüm yöntemlerin aynı mesaj dizisi türünden çağrıldığını doğrulamak için sınıfa tek bir mesaj dizisi ek açıklaması ekleyebilirsiniz.

İleti dizisi ek açıklamalarının yaygın bir kullanımı, @WorkerThread ile ek açıklama eklenen yöntemlerin veya sınıfların yalnızca uygun bir arka plan ileti dizisinden çağrıldığını doğrulamaktır.

Değer kısıtlaması ek açıklamaları

İletilen 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ış belirtme olasılığının yüksek olduğu parametrelere uygulandığında en yararlı olur.

@IntRange ek açıklaması, bir tam sayı veya uzun parametre değerinin belirtilen aralık içinde 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österir:

Kotlin

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

Java

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

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

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 ek açıklaması, bir koleksiyon veya dizinin boyutunu ya da 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 katları 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öntemi çağıran kişinin 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 grubu olup olmadığını kontrol etmek için allOf özelliğini kullanın. Aşağıdaki örnekte, setWallpaper() yönteminin açıklama notu eklenerek yöntemi çağıranın permission.SET_WALLPAPERS iznine sahip olması gerektiği belirtilmektedir:

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 örnek, copyImageFile() yöntemini çağıran kullanıcının hem harici depolama alanına okuma erişimi hem de kopyalanan görüntüdeki konum meta verilerine okuma erişimi olmasını gerektirir:

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 koşulunu, niyet 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";

İçerik sağlayıcılarda okuma ve yazma erişimi için ayrı izinlere ihtiyaç duyulan izinler için her izin koşulunu bir @RequiresPermission.Read veya @RequiresPermission.Write ek açıklama içine alı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, bir yöntemin parametresine sağlanan belirli değere bağlı olduğunda, belirli izinleri listelemeden parametrenin kendisinde @RequiresPermission kullanın. Örneğin, startActivity(Intent) yöntemi, yönteme iletilen intent ü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ı izinler kullandığınızda derleme araçları, yönteme iletilen bağımsız değişkende @RequiresPermission ek açıklamalarının olup olmadığını kontrol etmek için veri akışı analizi gerçekleştirir. Ardından, yöntemin kendisindeki parametreden mevcut ek açıklamaları uygular. startActivity(Intent) örneğinde, Intent sınıfındaki ek açıklamalar, yönteme uygun izinlere sahip olmayan bir intent iletildiğinde startActivity(Intent)'ün geçersiz kullanımlarıyla ilgili uyarıların gösterilmesine neden olur (Şekil 1'de gösterilmiştir).

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

Derleme araçları, startActivity(Intent) öğesinde Intent sınıfındaki ilgili intent işlemi adındaki ek açıklamadan 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 parametresine ek açıklama eklerken @RequiresPermission.Read veya @RequiresPermission.Write yerine @RequiresPermission 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öndürülen 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çıklamak yerine, kafa karıştırıcı olabilecek yöntemlerin sonuçlarını açıklamak için açıklama ekleyin.

Örneğin, yeni Java geliştiricileri genellikle <String>.trim() işlevinin orijinal dizedeki boşlukları kaldırdığını yanlış düşünür. Yönteme @CheckResult flag'leri ek açıklama eklemek, <String>.trim() öğesinin kullanımlarını çağıran kişinin yöntemin döndürülen değeriyle hiçbir şey yapmaması.

Aşağıdaki örnekte, yöntemin döndürdüğü değerin gerçekten referans alınıp alınmadığını kontrol etmek için checkPermissions() yöntemine ek açıklama eklenmiştir. Ayrıca, enforcePermission() yöntemini geliştiriciye önerilebilecek bir yöntem olarak da belirtir:

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ı

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

Aşağıdaki örnekte, geçersiz kılma yöntemi uygulamalarının super.onCreate()'u çağırmasını sağlamak için onCreate() yöntemine not eklenmiştir:

Kotlin

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

Java

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

Typedef ek açıklamaları

Tür tanımı ek açıklamaları, belirli bir parametrenin, döndürülen değerin veya alanın belirli bir sabitler grubuna atıfta bulunup bulunmadığını kontrol eder. Ayrıca, izin verilen sabitleri otomatik olarak sunmak için kod tamamlamayı etkinleştirirler.

Diğer kod referansı türlerini doğrulamak amacıyla, tam sayı ve dize kümelerinden oluşan numaralandırılmış ek açıklamalar oluşturmak için @IntDef ve @StringDef ek açıklamalarını kullanın.

Typedef ek açıklamaları, yeni listelenmiş 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 listelenen türü tanımlamak için gereklidir. @Retention(RetentionPolicy.SOURCE) ek açıklaması, derleyiciye listelenen 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 atıfta bulunup bulunmadığını kontrol eden bir ek 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 derlediğinizde, mode parametresi tanımlanmış sabitlerden birine (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST veya NAVIGATION_MODE_TABS) referans vermiyorsa bir uyarı oluşturulur.

Bir tam sayının belirli bir sabit değer grubu veya bir aralıktaki değer olabileceğini belirtmek için @IntDef ve @IntRange değerlerini birlikte kullanın.

Sabitleri işaretlerle birleştirmeyi etkinleştirme

Kullanıcılar izin verilen sabit değerleri bir işaretle (|, &, ^ vb.) birleştirebiliyorsa bir parametrenin veya döndürülen değerin geçerli bir kalıba referans verip vermediğini kontrol etmek için flag özelliğine sahip bir ek açıklama tanımlayabilirsiniz.

Aşağıdaki örnekte, geçerli DISPLAY_ sabitlerinin listesiyle DisplayOptions ek açıklama 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 {}

...

Kodu ek açıklama işaretiyle derlediğinizde, süslenmiş parametre veya döndürülen değer geçerli bir kalıba atıfta bulunmuyorsa uyarı oluşturulur.

Ek açıklamayı saklama

@Keep ek açıklaması, kod derleme sırasında küçültüldüğünde ek açıklamalı bir sınıfın veya yöntemin kaldırılmamasını sağlar. Bu ek açıklama, genellikle derleyicinin kodu kullanılmayan olarak işlemesini önlemek için yansıma 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ç atıfta bulunmasanız bile her zaman uygulamanızın APK'sında görünür.

Uygulamanızın boyutunu küçük tutmak için uygulamanızdaki her @Keep notasyonun korunmasının gerekli olup olmadığını düşünün. Notasyon eklenmiş bir sınıfa veya metoda erişmek için yansımayı kullanıyorsanız ProGuard kurallarınızda, yansıma çağrılarını yapan sınıfı belirterek -if koşullu ifadesi kullanın.

Kodunuzu nasıl küçülteceğiniz ve hangi kodun kaldırılmayacağını nasıl belirteceğiniz 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üğü ek açıklamaları

Kodun belirli bölümlerinin (ör. yöntemler, sınıflar, alanlar veya paketler) görünürlüğünü belirtmek için aşağıdaki ek açıklamaları kullanın.

Kodu test için görünür hale getirme

@VisibleForTesting notu, ek açıklamaya sahip bir yöntemin test edilebilir hale getirilmesi için normalden daha görünür olduğunu belirtir. Bu ek açıklama, test için görünür hale getirme ihtiyacı olmasaydı yöntemin görünürlüğünün ne olacağını belirtmenize olanak tanıyan isteğe bağlı bir otherwise bağımsız değişkenine sahiptir. Lint, istenen görünürlüğü sağlamak için otherwise bağımsız değişkenini kullanır.

Aşağıdaki örnekte myMethod() normalde private değeridir ancak testler için package-private değerine sahiptir. VisibleForTesting.PRIVATE ile işaretlenen yöntem, private erişiminin izin verdiği bağlamın dışından (ör. farklı bir derleme birimi) çağrılırsa lint bir mesaj görüntüler.

Kotlin

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

Java

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

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

API'yi kısıtlama

@RestrictTo ek açıklaması, ek açıklamalı 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 sınırlamak için @RestrictTo(RestrictTo.Scope.SUBCLASSES) ek açıklama formunu kullanın.

Bu API'ye yalnızca ek açıklama eklenmiş sınıfı genişleten sınıflar erişebilir. Java protected değiştiricisi, aynı paketteki alakasız sınıflardan erişime izin verdiği için yeterince kısıtlayıcı değildir. Ayrıca, daha önce protected ve geçersiz kılınmış bir public yöntemi oluşturamayacağınız için gelecekte esneklik sağlamak amacıyla bir public yöntemi bırakmak isteyebilirsiniz. Ancak sınıfın yalnızca sınıf içinde veya alt sınıflardan kullanıma yönelik olduğunu belirtmek için bir ipucu da sağlamak istersiniz.

Kütüphaneler

API erişimini yalnızca kitaplığınızla sınırlamak için @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) ek açıklama formunu kullanın.

Yalnızca kitaplık kodunuz ek açıklamalı API'ye erişebilir. Bu sayede kodunuzu istediğiniz paket hiyerarşisinde düzenleyebilir ve ilgili bir grup kitaplık arasında paylaşabilirsiniz. Bu seçenek, harici kullanıma yönelik olmayan ancak çeşitli tamamlayıcı Jetpack kitaplıkları arasında paylaşmak için public olması gereken çok sayıda uygulama koduna sahip Jetpack kitaplıkları tarafından zaten kullanılmaktadır.

Test

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

Ek açıklamalı API'ye yalnızca test kodu erişebilir. Bu, diğer geliştiricilerin API'leri yalnızca test amaçlı geliştirme için kullanmasını engeller.