Lint gibi kod denetleme araçlarını kullanmak, sorunları bulmanıza ve kodunuzu iyileştirmenize yardımcı olabilir ancak denetleme araçları yalnızca belirli bir noktaya kadar çı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, denetleme araçları, renk belirtmeniz gereken yerde dize kaynağı belirttiğinizi 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, lint gibi kod inceleme araçlarına ipuçları vererek bu daha belirsiz kod sorunlarını tespit etmenize yardımcı olur. Ek 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. Ek açıklamalar, kod inceleme araçlarıyla birlikte 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çıklamalar Kitaplığı aracılığıyla çeşitli ek açıklamaları destekler.
Kitaplığa androidx.annotation paketi üzerinden erişebilirsiniz.
Note: Bir modülün ek açıklama işleyicisine 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çı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 ek açıklamalar, 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 Annotations 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.11.0") }
Modern
dependencies { implementation 'androidx.annotation:annotation:1.11.0' }
Kendi kitaplık modülünüzde ek açıklamalar kullanırsanız ek açıklamalar, annotations.zip dosyasında XML biçiminde 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 alt kullanıcıları için bir bağımlılık oluşturmaz.
Note: 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 zaten 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 denetimlerini ç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 (Analiz et) > Inspect Code'u (Kodu İncele) 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österir.
Notları, komut satırını kullanarak lint görevini çalıştırarak da zorunlu kılabilirsiniz. Bu, sürekli entegrasyon sunucusuyla ilgili sorunları işaretlemek için yararlı olsa da lint görevi, boşluk ek açıklamalarını (aşağıdaki bölümde açıklanmıştır) zorunlu kılmaz. Bunu yalnızca Android Studio yapar. Lint denetimlerini etkinleştirme ve çalıştırma hakkında daha fazla bilgi için Lint kontrolleriyle kodunuzu iyileştirme başlıklı makaleyi inceleyin.
Ek açıklama çakışmaları uyarı oluştursa da bu uyarılar uygulamanızın derlenmesini engellemez.
Boşluk ek açıklamaları
Boşluk ek açıklamaları, değerlerin boş olup olamayacağını zorunlu kılmak için Java kodunda yararlı olabilir. Kotlin'de, derleme süresinde uygulanan yerleşik null değer alabilme kuralları olduğundan 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 ek açıklaması, boş olabilecek bir değişkeni, parametreyi veya dönüş değerini gösterir.
@NonNull, boş olamayacak bir değişkeni, parametreyi veya dönüş değerini gösterir.
Örneğin, boş değer içeren bir yerel değişken, @NonNull ek açıklaması eklenmiş bir yönteme parametre olarak iletilirse kodun derlenmesi, boş olmayan bir çakışma olduğunu belirten bir uyarı oluşturur. Ayrıca, @Nullable ile işaretlenmiş bir yöntemin sonucuna, sonucun boş olup olmadığını kontrol etmeden başvurmaya çalışmak boşluk uyarısı oluşturur. @Nullable ek açıklamasını bir yöntemin dönüş değerinde yalnızca yöntemin her kullanımının açıkça null kontrolü yapılması gerekiyorsa kullanın.
Aşağıdaki örnekte null değer alabilme özelliğinin kullanımı gösterilmektedir. Kotlin örnek kodu, null değer alabilen bir tür belirtildiğinde oluşturulan bayt koduna otomatik olarak eklendiği için @NonNull ek açıklamasından yararlanmaz. Java örneği, iletilen parametre değerlerinin boş olmadığını kontrol etmek için context ve attrs parametrelerinde @NonNull ek açıklamasını kullanı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) { ... } ...
Null değer alabilme analizi
Android Studio, kodunuzdaki null değer alabilme ek açıklamalarını otomatik olarak tahmin etmek ve eklemek için null değer alabilme analizi çalıştırmayı destekler. Null değer alabilme analizi, kodunuzdaki yöntem hiyerarşileri boyunca sözleşmeleri tarayarak şunları tespit eder:
- Null döndürebilen yöntemleri çağırma
- Boş değer döndürmemesi gereken yöntemler.
- Alanlar, yerel değişkenler ve parametreler gibi boş olabilen değişkenler.
- Boş değer barındıramayan alanlar, yerel değişkenler ve parametreler gibi değişkenler.
Ardından analiz, algılanan konumlara uygun null ek açıklamalarını otomatik olarak ekler.
Android Studio'da null değer alabilme analizi çalıştırmak için Analyze (Analiz et) > Infer Nullity'yi (Null değer alabilme çıkarımı yap) seçin. Android Studio, kodunuzda algılanan konumlara Android @Nullable ve @NonNull ek açıklamalarını ekler. Boşluk analizi yaptı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. Ancak Android Studio lint denetleyicisi yalnızca Android null ek açıklamalarını arar. Ek açıklamalarınızı doğrularken projenizin Android null ek açıklamalarını kullandığından emin olun. Böylece lint denetleyicisi, kod denetimi sırasında sizi doğru şekilde bilgilendirebilir.
Kaynak ek açıklamaları
Android'in drawable ve string dize kaynakları gibi kaynaklara referansları tam sayı olarak iletildiğinden kaynak türlerini doğrulamak faydalı olabilir.
Bir parametrenin belirli bir kaynak türüne (ör. String) referans vermesini bekleyen kod, beklenen referans türüne (int) iletilebilir ancak aslında farklı bir kaynak türüne (ör. R.string kaynağı) 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 denetimi sırasında, parametrede bir R.string referansı iletilmezse 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ü olabileceğini belirtmek için @AnyRes kullanın.
Bir parametrenin renk kaynağı olması gerektiğini belirtmek için @ColorRes kullanabilseniz de 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 hatalı kodları işaretler.
İleti dizisi ek açıklamaları
İş parçacığı ek açıklamaları, bir yöntemin belirli bir iş parçacığı türünden çağrılıp çağrılmadığını kontrol eder. Aşağıdaki ileti 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 çağırabilirsiniz ve bunun tersi de geçerlidir. Ancak farklı iş parçacıklarında birden fazla görünüme sahip sistem uygulamalarında kullanıcı arayüzü 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 ile, yalnızca uygulamanın yaşam döngüsüyle ilişkili yöntemlere ise @MainThread ile ek açıklama eklemeniz gerekir.
Bir sınıftaki tüm yöntemler aynı iş parçacığı şartını paylaşıyorsa sınıftaki tüm yöntemlerin aynı iş parçacığı türünden çağrıldığını doğrulamak için sınıfa tek bir iş parçacığı 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ıtlama notları
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ış anlayabileceği parametrelere uygulandığında en faydalı sonuçları verir.
@IntRange ek açıklaması, bir tam sayı veya uzun parametre değerinin belirtilen aralıkta olduğunu doğrular. Aşağıdaki örnekte, alpha parametresinin 0 ile 255 arasında bir tam sayı değeri içermesi gerektiği belirtilmektedir:
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 veya çift parametre değerinin, belirtilen kayan nokta değerleri aralığında olup olmadığını kontrol eder. Aşağıdaki örnekte, alpha parametresinin 0,0 ile 1,0 arasında bir kayan değer içermesi gerektiği gösterilmektedir:
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 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)) @Size(2)gibi tam boyut- 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ö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, yöntemi çağıranın permission.SET_WALLPAPERS iznine sahip olması gerektiğini belirtmek için setWallpaper() yöntemine ek açıklama eklenmektedir:
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) { //... }
Intent'lerle ilgili izinler için izin şartını, intent işlemi 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 izinler için her izin şartını bir @RequiresPermission.Read
veya @RequiresPermission.Write
ek açıklamasına 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 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ı izinleri kullandığınızda derleme araçları, yönteme iletilen bağımsız değişkende @RequiresPermission ek açıklamaları olup olmadığını kontrol etmek için veri akışı analizi gerçekleştirir. Ardından, parametredeki mevcut ek açıklamaları yöntemin kendisine uygularlar. startActivity(Intent) örneğinde, Intent sınıfındaki ek açıklamalar, uygun izinlere sahip olmayan bir intent yönteme iletildiğinde startActivity(Intent) öğesinin geçersiz kullanımlarıyla ilgili uyarıların gösterilmesine neden olur (Şekil 1'de gösterildiği gibi).
Şekil 1. startActivity(Intent) yöntemindeki dolaylı izin ek açıklamasından oluşturulan uyarı.
Derleme araçları, Intent sınıfındaki ilgili intent işlemi adındaki ek açıklamadan startActivity(Intent) ile ilgili uyarıyı 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. Geçersiz olmayan her yönteme @CheckResult eklemek 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() yönteminin orijinal dizedeki boşlukları kaldırdığını düşünür. Yönteme @CheckResult ile ek açıklama eklemek, arayanın yöntemin döndürdüğü değerle hiçbir şey yapmadığı <String>.trim() kullanımlarını işaretler.
Aşağıdaki örnekte, yöntemin döndürdüğü değere gerçekten referans verilip verilmediğini kontrol etmek için checkPermissions() yöntemine ek açıklama eklenmektedir. Ayrıca, geliştiriciye alternatif olarak önerilecek yöntem olarak enforcePermission() yöntemini 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ılan bir yöntemin, 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ılan yöntem uygulamalarının super.onCreate() yöntemini çağırmasını sağlamak için onCreate() yöntemi ek açıklamayla belirtilmiş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önüş değerinin veya alanın belirli bir sabit grubuna referans verip vermediğini kontrol eder. Ayrıca, izin verilen sabitleri otomatik olarak sunmak için kod tamamlamayı etkinleştirirler.
Diğer kod referansı türlerini doğrulamak için @IntDef ve @StringDef ek açıklamalarını kullanarak tam sayı ve dize kümelerinin numaralandırılmış ek açıklamalarını oluşturun.
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 ek 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ı 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 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ımlanan 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 sabitler kümesi veya bir aralıktaki değer olabileceğini belirtmek için @IntDef ve @IntRange ifadelerini birleştirin.
Sabitleri işaretlerle birleştirmeyi etkinleştirme
Kullanıcılar izin verilen sabitleri bir işaretle (ör. |, &, ^ 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 listesini içeren DisplayOptions ek açıklaması 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 {} ...
Ek açıklama işaretiyle kod oluşturduğunuzda, ek açıklamalı parametre veya dönüş değeri geçerli bir kalıba referans vermiyorsa uyarı oluşturulur.
Notu sakla
@Keep ek açıklaması, kod derleme sırasında sadeleştirildiğinde 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ılmamış olarak değerlendirmesini ö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ığı içinde bu sınıflara ve yöntemlere hiç 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ı değerlendirin. 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 sadeleştireceğ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ı
Yöntemler, 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.
Kodu test için görünür hale getirme
@VisibleForTesting
notu, açıklamalı bir yöntemin, yöntemi test edilebilir hale getirmek için normalde gerekenden daha görünür olduğunu gösterir. Bu ek açıklama, 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ş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 iken testler için package-private olarak ayarlanmıştır. VisibleForTesting.PRIVATE tanımıyla lint, bu yöntem private erişiminin izin verdiği bağlamın dışından (ör. farklı bir derleme biriminden) çağrılırsa 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 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çı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 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ı paketteki alakasız sınıflardan erişime izin verdiği için yeterince kısıtlayıcı değildir. Ayrıca, daha sonra esneklik sağlamak için bir yöntemi public bırakmak istediğiniz durumlar da olabilir. Çünkü daha önce protected ve geçersiz kılınmış bir yöntemi public yapamazsı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 istersiniz.
Kütüphaneler
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. 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şılabilmesi için public olması gereken çok sayıda uygulama kodu içeren Jetpack kitaplıklarında zaten mevcuttur.
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 sayede, diğer geliştiricilerin yalnızca test amacıyla kullanmayı planladığınız API'leri geliştirme için kullanması engellenir.