lint gibi kod inceleme araçlarını kullanmak, sorunları bulmanıza ve kodunuzu iyileştirmenize yardımcı olabilir. Ancak inceleme araçları, belirli bir konuda çıkarımda bulunabilir. Örneğin, Android kaynak kimlikleri; dizeleri, grafikleri, renkleri ve diğer kaynak türlerini tanımlamak için int
kullanır. Bu nedenle, denetleme araçları, renk belirtmeniz gereken bir yerde dize kaynağı belirtmiş olduğunuzu anlayamaz. 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. Ek 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
paketi aracılığıyla erişebilirsiniz.
Not: Bir modülün ek açıklama işlemcisine bağımlılığı varsa söz konusu bağımlılığı eklemek üzere 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 kitaplığınıza veya uygulamanıza androidx.annotation:annotation
bağımlılığını ekleyin. Eklediğiniz tüm notlar, bir kod incelemesi 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:
dependencies { implementation("androidx.annotation:annotation:1.9.1") }
dependencies { implementation 'androidx.annotation:annotation:1.9.1' }
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: Başka Jetpack kitaplıkları 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 zaten erişiminiz olabilir.
Jetpack deposunda bulunan ek açıklamaların tam listesi için Jetpack ek açıklamaları kitaplığı referansına bakın veya import androidx.annotation.
ifadesi için mevcut seçenekleri görüntülemek üzere otomatik tamamlama özelliğini kullanın.
Kod incelemeleri çalıştırma
Android Studio'da notları doğrulama ve otomatik dil bilgisi denetimi içeren bir kod denetimi başlatmak için menüden Analizin > 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ının uyarı oluşturmasına rağmen bu uyarılar uygulamanızın derlenmesini engellemez.
Boşluk ek açıklamaları
Java kodunda, değerlerin null olup olamayacağını zorunlu kılmak için boşluk ek açıklamaları 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ı, null olabilen bir değişkeni, parametreyi veya döndürülen değeri gösterir.
@NonNull
, null olamaz bir değişkeni, parametreyi veya döndürülen değeri gösterir.
Örneğin, boş değer içeren bir yerel değişken, bu parametreye @NonNull
ek açıklamasına sahip bir yönteme parametre olarak iletilirse kod oluşturulduğunda, boş olmayan bir çakışmayı gösteren uyarı oluşturulur. Ayrıca, önce sonucun boş olup olmadığını kontrol etmeden @Nullable
ile işaretlenmiş bir yöntemin sonucuna referans vermeye çalışmak da 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ği, iletilen parametre değerlerinin boş olmadığını kontrol etmek için context
ve attrs
parametrelerindeki @NonNull
ek açıklamasından yararlanır. Ayrıca onCreateView()
yönteminin kendisinin null döndürmediği de kontrol edilir:
... /** 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) { ... } ...
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şluk analizleri, kodunuzdaki yöntem hiyerarşileri boyunca sözleşmeleri tarayarak aşağıdakileri tespit eder:
- Boş değer döndürebilen çağrı yöntemleri.
- 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.
Daha sonra analiz, algılanan konumlara uygun boş ek açıklamaları otomatik olarak ekler.
Android Studio'da boş değer analizi çalıştırmak için Analiz et > Nullity'yi Çıkar'ı seçin. Android Studio, Android @Nullable
ve @NonNull
ek açıklamalarını kodunuzdaki 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. Ancak Android Studio lint kontrol aracı 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.
Bir parametrenin String
gibi belirli bir kaynak türünü referans almasını bekleyen kod, beklenen referans türü olan int
'e iletilebilir ancak aslında R.string
kaynağı gibi farklı bir kaynak türünü referans alabilir.
Örneğin, bir kaynak parametresinin R.string
referansı içerip içermediğini kontrol etmek için @StringRes
ek açıklamaları ekleyin.
abstract fun setTitle(@StringRes resId: Int)
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.
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 mesaj dizisi ek açıklamaları desteklenir:
Derleme araçları, @MainThread
ve @UiThread
ek açıklamalarını birbirinin yerine geçecek şekilde ele alır. Böylece @MainThread
yöntemlerinden @UiThread
yöntemlerini çağırabilir veya bunun tersini yapabilirsiniz. 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öntemleri @UiThread
ile, yalnızca bir uygulamanın yaşam döngüsüyle ilişkili yöntemleri ise @MainThread
ile ek açıklamalı hale getirmeniz 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.
@WorkerThread
ile ek açıklama yapılan yöntemlerin veya sınıfların yalnızca uygun bir arka plan iş parçacığında çağrıldığını doğrulamak, iş parçacığı ek açıklamalarının yaygın bir kullanımıdı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:
fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }
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:
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
@Size
ek 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)
) - Tam boyut (ör.
@Size(2)
) - Boyutun,
@Size(multiple=2)
gibi bir sayının katı olması gereken sayı
Ö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:
fun getLocation(button: View, @Size(min=1) location: IntArray) { button.getLocationOnScreen(location) }
void getLocation(View button, @Size(min=1) int[] location) { button.getLocationOnScreen(location); }
İzin ek açıklamaları
Bir yöntemi çağıranı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, setWallpaper()
yönteminin açıklama notu eklenerek yöntemi çağıranın permission.SET_WALLPAPERS
iznine sahip olması gerektiği belirtilmektedir:
@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;
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:
@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) { //... }
Niyetlerle ilgili izinler için izin koşulunu, niyet işlem adını tanımlayan dize alanına yerleştirin:
@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";
Okuma ve yazma erişimine yönelik ayrı izinlere ihtiyaç duyan içerik sağlayıcılardaki izinler için her izin koşulunu @RequiresPermission.Read
veya @RequiresPermission.Write
ek açıklamasıyla sarmalayın:
@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");
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:
abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)
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ı, Intent
sınıfındaki ilgili intent işlem adındaki ek açıklamayı kullanarak startActivity(Intent)
üzerinde uyarı oluşturur:
@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";
Gerekirse bir yöntemin parametresine ek açıklama eklerken @RequiresPermission.Read
veya @RequiresPermission.Write
yerine @RequiresPermission
kullanabilirsiniz. Ancak @RequiresPermission
, dolaylı izinler için 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 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ürülen değerine gerçekten referans verilip verilmediğini kontrol etmek için checkPermissions()
yöntemine ek açıklama eklenmiştir. Ayrıca enforcePermission()
yöntemini de geliştiriciye alternatif yöntem olarak önerilecek bir yöntem olarak adlandırır:
@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 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:
@CallSuper override fun onCreate(savedInstanceState: Bundle?) { }
@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 sabit değerleri otomatik olarak sunmak için kod tamamlamaya olanak tanır.
Diğer kod referansı türlerini doğrulamak için tam sayı ve dize gruplarının listelenmiş ek açıklamalarını oluşturmak üzere @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çıklamaya açıklama ekler ve numaralandırılmış 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:
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); }
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ğer grubu veya bir aralıktaki değer olabileceğini belirtmek için @IntDef
ve @IntRange
değerlerini birlikte kullanın.
Sabit değerleri işaretlerle birleştirmeyi etkinleştir
Kullanıcılar izin verilen sabitleri bir işaretle (|
, &
, ^
vb.) birleştirebiliyorsa bir parametrenin veya döndürülen değerin geçerli bir kalıba atıfta bulunup bulunmadığını kontrol etmek için flag
özelliğine sahip bir ek açıklama tanımlayabilirsiniz.
Aşağıdaki örnekte, geçerli DISPLAY_
sabit değerlerinin listesiyle DisplayOptions
ek açıklaması oluşturulur:
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 {} ...
Ek açıklama işaretiyle kod derlediğinizde, dekore edilmiş parametre veya döndürülen değer geçerli bir kalıbı referans göstermiyorsa uyarı oluşturulur.
Ek açıklamayı saklama
@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, derleyicinin kodu kullanılmamış olarak değerlendirmesini önlemek için genellikle 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, 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
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.
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) fun myMethod() { ... }
@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE) void myMethod() { ... }
Bir yöntemin yalnızca test için mevcut olduğunu belirtmek üzere @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çıklamaya sahip API'ye (paket, sınıf veya yöntem) erişimin aşağıdaki şekilde sınırlı olduğunu belirtir:
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.
Ek açıklamalı API'ye yalnızca kitaplık kodunuz 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.
Yalnızca test kodu, ek açıklamalı API'ye erişebilir. Bu, diğer geliştiricilerin API'leri yalnızca test amaçlı geliştirme için kullanmasını engeller.