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ı bununla sınırlı sayıda çıkarım yapabilir. Örneğin, Android kaynak kimlikleri dizeleri, grafikleri, renkleri ve diğer kaynak türlerini tanımlamak için int kullanır. Bu nedenle inceleme araçları, bir renk belirtmeniz gereken dize kaynağını ne zaman belirttiğinizi belirleyemez. Bu durum, kod incelemesini kullansanız bile uygulamanızın yanlış oluşturulabileceği veya hiç çalışmayabileceği anlamına gelir.

Ek açıklamalar, bu daha zor fark edilen kod sorunlarını tespit etmenize yardımcı olacak lint gibi kod inceleme araçlarına ipuçları sağlamanıza olanak tanır. Ek açıklamalar, yöntem döndürme değerlerini, geçirilen 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. Notlar, kod inceleme araçlarıyla kullanıldığında 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 üzerinden erişebilirsiniz.

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

Projenize ek açıklama ekleyin

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, bir kod incelemesi veya lint görevi çalıştırdığınızda kontrol edilir.

Jetpack Ek Açıklamaları kitaplığı bağımlılığını ekleme

Jetpack Notlar kitaplığı Google'ın Maven deposunda yayınlanmıştır. Projenize Jetpack Anotations kitaplığını 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.7.1")
}

Modern

dependencies {
    implementation 'androidx.annotation:annotation:1.7.1'
}
Ardından, araç çubuğunda veya görünen senkronizasyon bildiriminde Şimdi Senkronize Et'i tıklayın.

Kendi kitaplık modülünüzde ek açıklamaları kullanıyorsanız bu ek açıklamalar, Android Arşivi (AAR) yapısının bir parçası olarak annotations.zip dosyasına XML biçiminde bir şekilde dahil edilir. androidx.annotation bağımlılığının eklenmesi, kitaplığınızın aşağı akış kullanıcıları için bir bağımlılık teşkil etmez.

Not: Başka 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çıklamaları kitaplık başvurusu'na bakın veya import androidx.annotation. ifadesiyle ilgili mevcut seçenekleri görüntülemek için otomatik tamamlama özelliğini kullanın.

Kod denetimlerini çalıştırma

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

Ek açıklamaları, komut satırını kullanıp lint görevini çalıştırarak da zorunlu kılabilirsiniz. Bu, sürekli entegrasyon sunucusuyla ilgili sorunların işaretlenmesinde yararlı olsa da lint görevi boş değer ek açıklamalarını zorunlu kılmaz (aşağıdaki bölümde açıklanmıştır); bunu yalnızca Android Studio yapar. lint denetimlerini etkinleştirme ve çalıştırma hakkında daha fazla bilgi için Kodunuzu lint denetimleriyle iyileştirme bölümüne bakın.

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

Boşluk ek açıklamaları

Boş değer ek açıklamaları, Java kodunda değerlerin boş olup olamayacağını zorlamak için yararlı olabilir. Kotlin, derleme sırasında uygulanan null değer kuralı derlediği için Kotlin kodunda daha az faydalıdırlar.

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ş olabilecek bir değişkeni, parametreyi veya dönüş değerini belirtir. @NonNull, boş olamayacak 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, bu parametreye @NonNull ek açıklaması eklenmiş bir yönteme parametre olarak aktarılırsa kodun oluşturulması, boş olmayan bir çakışma olduğunu belirten bir uyarı oluşturur. Ayrıca, önce sonucun null olup olmadığını kontrol etmeden @Nullable tarafından işaretlenen bir yöntemin sonucuna referans vermeye çalışmak boşluk uyarısı üretir. @Nullable özelliğini yalnızca yöntemin her kullanımının açık bir şekilde boş işaretli olması gerekiyorsa kullanın.

Aşağıdaki örnekte boş değer atanabilirliği gösterilmektedir. Kotlin örnek kodu, null yapılamayan bir tür belirtildiğinde oluşturulan bayt koduna otomatik olarak eklendiğinden @NonNull ek açıklamasını kullanmaz. Java örneğinde, iletilen parametre değerlerinin boş olup olmadığını kontrol etmek için context ve attrs parametrelerindeki @NonNull ek açıklaması kullanılır. Ayrıca, onCreateView() yönteminin boş döndürmediğini 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 analizi

Android Studio, kodunuza boş değer ek açıklamalarını otomatik olarak tahmin etmek ve eklemek için null değer analizi çalıştırmayı destekler. Boş değer analizi, aşağıdakileri algılamak için kodunuzdaki yöntem hiyerarşileri genelinde sözleşmeleri tarar:

  • Boş değer döndürebilen çağrı yöntemleri.
  • Boş döndürmemesi gereken yöntemler.
  • Boş olabilecek alanlar, yerel değişkenler ve parametreler gibi değişkenler.
  • Boş değer alamayan alanlar, yerel değişkenler ve parametreler gibi değişkenler.

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

Android Studio'da null değer analizi çalıştırmak için Analiz et > Boşluk çıkarımı'nı seçin. Android Studio, Android @Nullable ve @NonNull ek açıklamalarını kodunuzda algılanan konumlara ekler. Boş analiz çalıştırdıktan sonra, eklenen ek açıklamaları doğrulamak iyi bir uygulamadır.

Not: Boş değer ek açıklamaları eklerken otomatik tamamlama, Android null 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 boş ek açıklamalarını arar. Ek açıklamalarınızı doğrularken projenizin null ek açıklamalarını kullandığını onaylayın. Böylece lint denetleyicisi, kod incelemesi sırasında sizi doğru şekilde bilgilendirebilir.

Kaynak ek açıklamaları

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

Bir parametrenin String gibi belirli bir kaynağa başvurmasını bekleyen kod, beklenen int referans türüne geçirilebilir, ancak aslında R.string kaynağı gibi farklı bir kaynağa başvuruda bulunabilir.

Örneğin, bir kaynak parametresinin R.string referansı içerip içermediğini kontrol etmek için burada gösterildiği gibi @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, parametrede R.string referansı geçirilmezse 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 incelemesi 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ı yerleştirebilirsiniz. Ek açıklamalı parametrenin herhangi bir R kaynağı olabileceğini belirtmek için @AnyRes kullanın.

Bir parametrenin bir renk kaynağı olması gerektiğini belirtmek için @ColorRes kullanabilirsiniz ancak bir renk tam sayısı (RRGGBB veya AARRGGBB biçiminde) 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ı, ek açıklamalı yöntemlere renk tam sayısı yerine android.R.color.black gibi bir renk kaynağı kimliği ileten yanlış kodları işaretler.

Mesaj 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 iş parçacığı ek açıklamaları desteklenir:

Derleme araçları @MainThread ve @UiThread ek açıklamalarını birbirinin yerine kullanılabilir olarak işler. Bu nedenle, @MainThread yöntemlerinden @UiThread yöntemlerini veya tersini çağırabilirsiniz. Bununla birlikte, farklı iş parçacıklarında birden çok görünümü olan sistem uygulamaları söz konusu olduğunda, UI iş parçacığı ana iş parçacığından farklı olabilir. Bu nedenle, bir uygulamanın görünüm hiyerarşisiyle ilişkili yöntemlere @UiThread ve yalnızca uygulamanın yaşam döngüsüyle ilişkilendirilen yöntemlere @MainThread ile ek açıklama eklemeniz gerekir.

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

İş parçacığı ek açıklamalarının yaygın bir kullanımı, @WorkerThread ek açıklamasına sahip 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 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 en çok, kullanıcıların aralığı yanlış anlamasının muhtemel olduğu parametrelere uygulandığında yararlıdır.

@IntRange ek açıklaması, bir tam sayı veya uzun parametre değerinin belirtilen bir 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 belirtir:

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ı, kayan nokta değeri veya çift parametre değerinin belirtilen bir kayan nokta değeri 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 belirtir:

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 koleksiyonun 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))
  • Tam 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 örnek, location dizisinin en az bir öğe içermesi gerektiğini belirtir:

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 listesinde 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 kişinin permission.SET_WALLPAPERS iznine sahip olması gerektiğini belirtmek için setWallpaper() yöntemi ek açıklaması eklenmiştir:

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 kişinin kopyalanan görüntüdeki hem harici depolama alanına okuma hem de konum meta verilerine okuma erişimine sahip 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 gereksinimini amaç 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ı izinlere ihtiyaç duyan içerik sağlayıcılardaki izinler için her bir 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, bir yöntemin parametresine sağlanan spesifik değere bağlı olduğunda belirli izinleri listelemeden parametrede @RequiresPermission kullanın. Örneğin, startActivity(Intent) yöntemi, yönteme iletilen niyet ü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 geçirilen bağımsız değişkende herhangi bir @RequiresPermission ek açıklaması olup olmadığını kontrol etmek için veri akışı analizi gerçekleştirir. Daha sonra yöntemin kendisindeki parametrede bulunan mevcut ek açıklamaları zorunlu kılarlar. startActivity(Intent) örneğindeki Intent sınıfındaki ek açıklamalar, Şekil 1'de gösterildiği gibi yönteme uygun izinlere sahip olmayan bir amaç iletildiğinde, geçersiz startActivity(Intent) kullanımlarında uyarılara neden olur.

Şekil 1. startActivity(Intent) yöntemindeki dolaylı izin ek açıklamasından oluşturulan uyarı.

Derleme araçları, startActivity(Intent) uygulamasında Intent sınıfındaki ilgili amaç 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 yaparken @RequiresPermission.Read yerine @RequiresPermission yerine @RequiresPermission.Write kullanabilirsiniz. Ancak dolaylı izinler için @RequiresPermission, okuma veya yazma izinleri ek açıklamalarıyla birlikte kullanılmamalıdır.

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

Bir yöntemin sonuç 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öntem için @CheckResult ile ek açıklama girmek yerine, kafa karıştırıcı olabilecek yöntemlerin sonuçlarını netleştirmek için ek açıklama ekleyin.

Örneğin, yeni Java geliştiricileri genellikle <String>.trim() ürününün orijinal dizedeki boşlukları kaldırdığını düşünebilir. Yöntemin @CheckResult flag'leriyle ek açıklaması, çağrıyı yapanın yöntemin döndürülen değeriyle hiçbir şey yapmadığı <String>.trim() kullanımlarını işaret eder.

Aşağıdaki örnek, yöntemin döndürülen değerine gerçekten referans verilip verilmediğini kontrol etmek için checkPermissions() yöntemine ek açıklama ekler. Ayrıca enforcePermission() yöntemi, geliştiriciye bunun yerine önerilecek yöntem olarak adlandırılı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ı

Geçersiz kılma yönteminin, yöntemin üzerine yazılması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() yöntemini çağırdığından emin olmak için onCreate() yöntemine ek açıklama eklenmiştir:

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öndürülen değerin veya alanın belirli bir sabit değer kümesine referans verip vermediğini kontrol eder. Ayrıca kod tamamlamanın, izin verilen sabit değerleri otomatik olarak sunmasına da olanak tanır.

Diğer kod referansı türlerini doğrulamak amacıyla tam sayı ve dize kümelerinden sıralı ek açıklamalar oluşturmak için @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çıklamaya açıklama 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ı bildirir.

Aşağıdaki örnekte, yöntem parametresi olarak iletilen bir değerin tanımlanan sabit değerlerden birine başvuruda 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 oluşturduğunuzda, mode parametresi tanımlı sabit değerlerden birine (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST veya NAVIGATION_MODE_TABS) başvuruda bulunmuyorsa bir uyarı oluşturulur.

Bir tam sayının belirli bir sabit değerler kümesi veya bir aralık içindeki bir değer olabileceğini belirtmek için @IntDef ve @IntRange değerlerini birlikte kullanın.

Sabit değerleri işaretlemelerle birleştirmeyi etkinleştir

Kullanıcılar izin verilen sabit değerleri bir bayrakla (|, &, ^ vb.) birleştirebiliyorsa bir parametrenin veya dönüş değerinin geçerli bir kalıba referansta bulunup bulunmadığını kontrol etmek için flag özelliğiyle bir ek açıklama tanımlayabilirsiniz.

Aşağıdaki örnek, geçerli DISPLAY_ sabit değerleri listesiyle DisplayOptions ek açıklamasını oluşturur:

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

...

Ek açıklama işaretiyle kod oluşturduğunuzda, sunulan parametre veya döndürülen değer geçerli bir kalıpa başvurmuyorsa bir uyarı oluşturulur.

Ek açıklamayı sakla

@Keep ek açıklaması, derleme sırasında kod 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öntem 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ıf ve yöntemlere hiçbir zaman referans vermeseniz 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 ek açıklamasını korumanın gerekli olup olmadığını düşünün. Ek açıklamalı bir sınıfa veya yönteme erişmek için yansıma kullanıyorsanız ProGuard kurallarınızda, yansıma çağrılarını yapan sınıfı belirten bir -if koşulu kullanın.

Kodunuzu nasıl küçülteceğiniz ve hangi kodun kaldırılmayacağını nasıl belirteceğiniz hakkında daha fazla bilgi edinmek için Uygulamanızı küçültme, gizleme ve optimize etme bölümüne bakın.

Kod görünürlüğü ek açıklamaları

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

Kodu test için görünür yap

@VisibleForTesting ek açıklaması, ek açıklamalı bir yöntemin, yöntemi test edilebilir hale getirmek için normalde gerekenden daha görünür olduğunu belirtir. Bu ek açıklamada, test için görünür hale getirme ihtiyacı duyulmuyorsa 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şkeni vardır. Lint, istenen görünürlüğü sağlamak için otherwise bağımsız değişkenini kullanır.

Aşağıdaki örnekte myMethod() normal olarak private değerine sahiptir ancak testler için package-private değerine sahiptir. Bu yöntem private erişiminin izin verdiği bağlamın dışından (ör. farklı bir derleme biriminden) çağrılırsa lint, VisibleForTesting.PRIVATE atamasıyla birlikte bir mesaj gösterir.

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) kullanımı ile aynıdır. Her ikisi de aynı hata analizi kontrolünü gerçekleştirir.

API'leri Kısıtla

@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 belirtir:

Alt sınıflar

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

Yalnızca ek açıklamalı sınıfı genişleten sınıflar bu API'ye erişebilir. Java 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 protected yöntemini ve geçersiz kılınan public yöntemini hiçbir zaman yapamayacağınız ancak sınıfın yalnızca sınıf içindeki veya alt sınıflardaki kullanımlar için tasarlandığına dair ipucu vermek istediğiniz için ileride esneklik kazanmak amacıyla bir public yöntemini bırakmak istediğiniz durumlar da vardır.

Kitaplıklar

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

Ek açıklamalı API'ye yalnızca kitaplık kodunuz erişebilir. Böylece hem kodunuzu istediğiniz paket hiyerarşisinde düzenleyebilir hem de ilgili kitaplıklar grubu arasında paylaşabilirsiniz. Bu seçenek, harici kullanıma yönelik olmayan birçok uygulama koduna sahip Jetpack kitaplıklarında zaten kullanılabilir ancak bunu çeşitli tamamlayıcı Jetpack kitaplıklarında paylaşabilmek için public olması gerekir.

Test etme

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

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