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. Böylece inceleme araçları, renk belirtmeniz gereken bir dize kaynağını belirttiğinizi belirleyemez. Bu durum, kod inceleme kullansanız bile uygulamanızın yanlış oluşturulabileceği veya hiç çalışmayabileceği anlamına gelir.
Notlar, lint gibi kod inceleme araçlarına ipuçları sağlayarak bu karmaşık kod sorunlarını tespit etmenize yardımcı olur. 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 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ş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 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 notlar, bir kod incelemesi veya lint görevi çalıştırdığınızda kontrol edilir.
Jetpack Notlar kitaplığına bağımlılığı ekleme
Jetpack Notlar kitaplığı, Google'ın Maven deposunda yayınlanmıştır.
Projenize Jetpack Ek Açıklamalar 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.8.0")
}
Eski
dependencies {
implementation 'androidx.annotation:annotation:1.8.0'
}
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 aşağı akış kullanıcıları için bir bağımlılık teşkil etmez.
Not: Başka Jetpack kitaplıkları 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 incelemeleri çalıştırma
Android Studio'dan, ek açıklamaları doğrulama ve otomatik hata analizi denetimini 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ığı olası sorunları işaretlemek ve olası çözümler önermek için çakışma mesajları gösterir.
Ayrıca komut satırını kullanıp lint görevini çalıştırarak ek açıklamaları zorunlu kılabilirsiniz. Bu, sürekli entegrasyon sunucusuyla ilgili sorunları işaretlemek için yararlı olabilir ancak lint görevi, boşluk ek açıklamalarını zorunlu kılmaz (aşağıdaki bölümde açıklanmıştır); 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 sırasında uygulanan boş değer atanabilirlik kuralları oluşturduğundan, bunlar Kotlin kodunda daha az faydalı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, boş olamayacak 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, 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 yöntemini yalnızca bir yöntemin her kullanımının açıkça null-işaretli olarak işaretlenmesi gerekiyorsa yöntemin döndürdüğü değerde kullanın.
Aşağıdaki örnekte, işlem sırasında boş değer gösterilmektedir. Kotlin örnek kodu, null olmayan bir tür belirtildiğinde oluşturulan bayt koduna otomatik olarak eklendiğinden @NonNull ek açıklamasından yararlanmaz. Java örneği, iletilen parametre değerlerinin null olmadığını kontrol etmek için context ve attrs parametrelerindeki @NonNull ek açıklamasından yararlanır. Ayrıca onCreateView() yönteminin kendisinin null değer 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 atanabilirlik analizi
Android Studio, boş değer ek açıklamalarını otomatik olarak tahmin etmek ve kodunuza eklemek için boş değer analizi yapmayı 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ürebilen çağrı yöntemleri.
- Null döndürmemesi gereken yöntemler.
- Boş değerli olabilecek alanlar, yerel değişkenler ve parametreler gibi değişkenler.
- Boş değer içermeyen alanlar, yerel değişkenler ve parametreler gibi değişkenler.
Daha sonra analiz, algılanan konumlara uygun boş ek açıklamaları otomatik olarak ekler.
Android Studio'da boş değer atanabilirlik analizi çalıştırmak için Analiz et > Nullity'yi Çıkar'ı seçin. Android Studio, kodunuzda algılanan konumlara Android @Nullable ve @NonNull ek açıklamalarını ekler. Boş analiz çalıştırdıktan sonra, yerleştirilen 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 null ek açıklamalarını arar. Ek açıklamalarınızı doğrularken, lint denetleyicisinin kod incelemesi sırasında sizi doğru şekilde bilgilendirebilmesi için projenizde Android null ek açıklamalarının kullanıldığını onaylayın.
Kaynak ek açıklamaları
Çekilebilir ve dize kaynakları gibi kaynaklara yapılan Android referansları tam sayı olarak geçirildiği için 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 burada gösterildiği gibi R.string referansı içerip içermediğini kontrol etmek için @StringRes ek açıklamaları ekleyin:
Kotlin
abstract fun setTitle(@StringRes resId: Int)
Java
public abstract void setTitle(@StringRes int resId)
Kod incelemesi sırasında, parametrede R.string referansı geçilmezse ek açıklama bir uyarı oluşturur.
@DrawableRes, @DimenRes, @ColorRes ve @InterpolatorRes gibi diğer kaynak türlerine yönelik 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ğı türünde olabileceğini belirtmek için @AnyRes kullanın.
Bir parametrenin 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 bir 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 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 iş parçacığı türünden çağrılıp çağrılmadığını kontrol eder. Aşağıdaki ileti dizisi notları 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çacıklarında birden çok görünüme sahip 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 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ı iş parçacığı gereksinimini 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ı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ış anlayabileceği parametrelere uygulandığında işe yarar.
@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 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ı, kayan nokta veya çift parametre değerinin belirtilen bir kayan nokta değerleri aralığında olup olmadığını kontrol eder. Aşağıdaki örnek, alpha parametresinin 0,0 ile 1,0 arasında bir kayan noktalı değer içermesi gerektiğini gösterir:
Kotlin
fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}
Java
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
@Size 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)) - Tam 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 örnek, location dizisinin en az bir öğe içermesi gerektiğini gösterir:
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, yöntemi çağıran kişinin permission.SET_WALLPAPERS iznine sahip olması gerektiğini belirtmek için setWallpaper() yöntemi ek açıklamaktadır:
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) {
//...
}
Amaçlarla ilgili izinler için amaç işlemi adını tanımlayan dize alanına izin şartını 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ş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:
Kotlin
@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS))
val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")
Java
@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS))
public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");
Dolaylı izinler
Bir izin, yöntemin parametresine sağlanan 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ı 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çıklaması olup olmadığını kontrol etmek için veri akışı analizi gerçekleştirir. Daha sonra, yöntemin kendisindeki parametrede bulunan mevcut notları uygularlar. startActivity(Intent) örneğinde, Intent sınıfındaki ek açıklamalar, Şekil 1'de gösterildiği gibi yönteme uygun izinlere sahip olmayan bir intent aktarıldığında startActivity(Intent) öğesinin geçersiz kullanımlarında ortaya çıkan uyarılara neden olur.
Şekil 1. startActivity(Intent) yöntemindeki dolaylı izin ek açıklamasından 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 açıklama eklerken @RequiresPermission yerine @RequiresPermission.Read veya @RequiresPermission.Write kullanabilirsiniz. Ancak @RequiresPermission, dolaylı izinler için okuma veya yazma izinleri ek açıklamalarıyla birlikte kullanılmamalıdır.
Döndürme değeri 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 ile not 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 yanlışlıkla <String>.trim() işlevinin orijinal dizedeki boşluğu kaldırdığını düşünebilir. 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:
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, tüm geçersiz kılma yöntemi uygulamalarının super.onCreate() çağrısı yapmasını sağlamak için onCreate() yöntemi ek açıklamaktadır:
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 grubuna başvurup vurmadığı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 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 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ı bildirir.
Aşağıdaki örnekte, yöntem parametresi olarak iletilen bir değerin tanımlanan sabit değerlerden 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ı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 sayı veya aralık içindeki bir değer olabileceğini belirtmek için @IntDef ve @IntRange özelliklerini birleştirin.
Sabit değerleri işaretlerle birleştirmeyi etkinleştir
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_ sabit değerlerinin listesiyle DisplayOptions ek açıklaması oluşturulur:
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 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ı koru
@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öntemlere ve sınıflara eklenir.
Dikkat: @Keep kullanarak ek açıklama eklediğiniz sınıflar ve yöntemler, uygulamanızın mantığında bu sınıflara ve yöntemlere hiçbir zaman referans vermeseniz bile 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 yansıma çağrılarını yapan sınıfı belirterek ProGuard kurallarınızda
-if koşulunu kullanın.
Kodunuzu küçültme ve kaldırılmayacak kodu belirleme hakkında daha fazla bilgi için Uygulamanızı küçültme, gizleme ve optimize etme bölümüne bakın.
Kod görünürlüğüyle ilgili 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 gerekli olandan daha görünür olduğunu belirtir. Bu ek açıklamada, test için görünür hale getirme ihtiyacı olmadığında yöntemin görünürlüğünü belirtmenize olanak tanıyan isteğe bağlı bir otherwise bağımsız değişkeni bulunur. 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ğerindedir ancak testler için package-private değeridir. VisibleForTesting.PRIVATE tanımlamasıyla birlikte lint yöntemi, 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ğerini de belirtebilirsiniz. Bu form, @RestrictTo(TESTS) kullanımı ile aynıdır. Her ikisi de aynı lint kontrolünü gerçekleştirir.
API'leri 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 önce protected ve public yöntemini hiçbir zaman oluşturamayacağınız, ancak sınıfın yalnızca sınıf içindeki veya alt sınıflardaki kullanımlara yönelik olduğuna dair bir ipucu vermek istediğiniz için gelecekteki esneklik için public yöntemini bırakmak isteyebileceğiniz durumlar da vardır.
Kitaplıklar
API erişimini yalnızca kitaplıklarınıza 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 kodunuzu istediğiniz paket hiyerarşisinde düzenleyebilir ve ilgili kitaplıklar grubu arasında paylaşabilirsiniz. Bu seçenek, harici kullanıma uygun olmayan büyük miktarda uygulama koduna sahip Jetpack kitaplıklarında zaten mevcuttur. Ancak kodu, çeşitli tamamlayıcı Jetpack kitaplıklarında paylaşmak için bunun 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 kodu erişebilir. Bu, diğer geliştiricilerin API'leri yalnızca test amaçlı geliştirme için kullanmasını engeller.