Migliora l'ispezione del codice con le annotazioni

L'utilizzo di strumenti di ispezione del codice, come lint, può aiutarti a trovare problemi e migliorare il codice, ma gli strumenti di ispezione possono solo dedurre. Gli ID risorsa Android, ad esempio, utilizzano un int per identificare stringhe, elementi grafici, colori e altri tipi di risorse, pertanto gli strumenti di ispezione non possono rilevare quando hai specificato una risorsa stringa anziché un colore. Questa situazione significa che il rendering della tua app potrebbe non essere corretto o l'app potrebbe non essere eseguita, anche se utilizzi l'ispezione del codice.

Le annotazioni ti consentono di fornire suggerimenti a strumenti di ispezione del codice, come lint, per rilevare questi problemi di codice più sottili. Le annotazioni vengono aggiunte come tag di metadati che vengono allegati a variabili, parametri e valori restituiti per esaminare i valori restituiti del metodo, i parametri passati, le variabili locali e i campi. Se utilizzate con strumenti di ispezione del codice, le annotazioni possono aiutarti a rilevare problemi come eccezioni di puntatore nullo e conflitti di tipo di risorsa.

Android supporta una serie di annotazioni tramite la libreria Jetpack Annotations. Puoi accedere alla libreria tramite il pacchetto androidx.annotation.

Nota: se un modulo ha una dipendenza da un processore di annotazioni, devi utilizzare la configurazione delle dipendenze kapt o ksp per Kotlin o la configurazione delle dipendenze annotationProcessor per Java per aggiungere la dipendenza.

Aggiungere annotazioni al progetto

Per attivare le annotazioni nel tuo progetto, aggiungi la dipendenza androidx.annotation:annotation alla tua libreria o app. Tutte le annotazioni che aggiungi vengono controllate quando esegui un'ispezione del codice o un'attività lint.

Aggiungi la dipendenza della libreria Jetpack Annotations

La libreria Jetpack Annotations è pubblicata nel repository Maven di Google. Per aggiungere la libreria Jetpack Annotations al tuo progetto, includi la seguente riga nel blocco dependencies del file build.gradle o build.gradle.kts:

dependencies {
    implementation("androidx.annotation:annotation:1.10.0")
}

dependencies {
    implementation 'androidx.annotation:annotation:1.10.0'
}

Se utilizzi le annotazioni nel tuo modulo della libreria, queste vengono incluse come parte dell'artefatto Android Archive (AAR) in formato XML nel file annotations.zip. L'aggiunta della dipendenza androidx.annotation non introduce una dipendenza per gli utenti downstream della tua libreria.

Nota: se utilizzi altre librerie Jetpack, potresti non dover aggiungere la dipendenza androidx.annotation. Poiché molte altre librerie Jetpack dipendono dalla libreria Annotations, potresti già avere accesso alle annotazioni.

Per un elenco completo delle annotazioni incluse nel repository Jetpack, consulta il riferimento della libreria Jetpack Annotations o utilizza la funzionalità di completamento automatico per visualizzare le opzioni disponibili per l'istruzione import androidx.annotation..

Esegui ispezioni del codice

Per avviare un'ispezione del codice da Android Studio, che include la convalida delle annotazioni e il controllo lint automatico, seleziona Analyze (Analizza) > Inspect Code (Ispeziona codice) dal menu. Android Studio mostra messaggi di conflitto per segnalare potenziali problemi in cui il codice è in conflitto con le annotazioni e per suggerire possibili soluzioni.

Puoi anche applicare le annotazioni eseguendo l'attività lint utilizzando la riga di comando. Sebbene questa funzionalità possa essere utile per segnalare problemi con un server di integrazione continua, l'attività lint non applica le annotazioni di nullità (descritte nella sezione seguente); solo Android Studio lo fa. Per ulteriori informazioni sull'attivazione e l'esecuzione di ispezioni lint, consulta Migliorare il codice con i controlli lint.

Sebbene i conflitti di annotazione generino avvisi, questi non impediscono la compilazione dell'app.

Annotazioni di nullità

Aggiungi le annotazioni @Nullable e @NonNull per verificare la nullità di una determinata variabile, parametro o valore restituito. L'annotazione @Nullable indica una variabile, un parametro o un valore restituito che può essere null. @NonNull indica una variabile, un parametro o un valore restituito che non può essere nullo.

Ad esempio, se una variabile locale che contiene un valore null viene passata come parametro a un metodo con l'annotazione @NonNull allegata a quel parametro, la compilazione del codice genera un avviso che indica un conflitto non null. Inoltre, il tentativo di fare riferimento al risultato di un metodo contrassegnato da @Nullable senza prima verificare se il risultato è nullo genera un avviso di nullità. Utilizza @Nullable sul valore restituito di un metodo solo se ogni utilizzo del metodo deve essere esplicitamente controllato per verificare la presenza di valori nulli.

L'esempio seguente mostra il supporto di valori null in azione. Il codice di esempio Kotlin non utilizza l'annotazione @NonNull perché viene aggiunta automaticamente al bytecode generato quando viene specificato un tipo non nullabile. L'esempio Java utilizza l'annotazione @NonNull sui parametri context e attrs per verificare che i valori dei parametri passati non siano nulli. Inoltre, verifica che il metodo onCreateView() non restituisca un valore nullo:

...
    /** 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) {
      ...
      }
...

Analisi di nullabilità

Android Studio supporta l'esecuzione di un'analisi di nullabilità per dedurre e inserire automaticamente le annotazioni di nullità nel codice. Un'analisi di nullabilità esamina i contratti in tutte le gerarchie dei metodi nel codice per rilevare:

• Metodi di chiamata che possono restituire valori null.
• Metodi che non devono restituire valori null.
• Variabili, come campi, variabili locali e parametri, che possono essere nulle.
• Variabili, ad esempio campi, variabili locali e parametri, che non possono contenere un valore nullo.

L'analisi inserisce quindi automaticamente le annotazioni null appropriate nelle posizioni rilevate.

Per eseguire un'analisi di nullabilità in Android Studio, seleziona Analizza > Inferisci nullità. Android Studio inserisce le annotazioni Android @Nullable e @NonNull nelle posizioni rilevate nel codice. Dopo aver eseguito un'analisi nulla, è buona norma verificare le annotazioni inserite.

Nota:quando aggiungi annotazioni di nullità, il completamento automatico potrebbe suggerire le annotazioni IntelliJ @Nullable e @NotNull anziché le annotazioni di nullità di Android e potrebbe importare automaticamente la libreria corrispondente. Tuttavia, il controllo lint di Android Studio cerca solo le annotazioni di nullità di Android. Quando verifichi le annotazioni, assicurati che il tuo progetto utilizzi le annotazioni di nullabilità di Android in modo che il controllo lint possa avvisarti correttamente durante l'ispezione del codice.

Annotazioni delle risorse

La convalida dei tipi di risorse può essere utile perché i riferimenti di Android alle risorse, come le risorse drawable e string, vengono passati come numeri interi.

Il codice che prevede che un parametro faccia riferimento a un tipo specifico di risorsa, ad esempio un String, può essere passato al tipo di riferimento previsto di int, ma in realtà fare riferimento a un tipo diverso di risorsa, ad esempio una risorsa R.string.

Ad esempio, aggiungi annotazioni @StringRes per verificare se un parametro di risorsa contiene un riferimento R.string, come mostrato qui:

abstract fun setTitle(@StringRes resId: Int)

public abstract void setTitle(@StringRes int resId)

Durante l'ispezione del codice, l'annotazione genera un avviso se un riferimento R.string non viene passato nel parametro.

Le annotazioni per altri tipi di risorse, come @DrawableRes, @DimenRes, @ColorRes e @InterpolatorRes, possono essere aggiunte utilizzando lo stesso formato di annotazione ed eseguite durante l'ispezione del codice.

Se il parametro supporta più tipi di risorse, puoi inserire più di un'annotazione del tipo di risorsa in un determinato parametro. Utilizza @AnyRes per indicare che il parametro annotato può essere qualsiasi tipo di risorsa R.

Anche se puoi utilizzare @ColorRes per specificare che un parametro deve essere una risorsa di colore, un numero intero di colore (nel formato RRGGBB o AARRGGBB) non viene riconosciuto come risorsa di colore. Utilizza invece l'annotazione @ColorInt per indicare che un parametro deve essere un numero intero di colore. Gli strumenti di compilazione segnaleranno il codice errato che passa un ID risorsa colore come android.R.color.black, anziché un numero intero di colore, ai metodi annotati.

Annotazioni thread

Le annotazioni dei thread verificano se un metodo viene chiamato da un tipo specifico di thread. Sono supportate le seguenti annotazioni dei thread:

• @MainThread
• @UiThread
• @WorkerThread
• @BinderThread
• @AnyThread

Gli strumenti di compilazione considerano le annotazioni @MainThread e @UiThread intercambiabili, quindi puoi chiamare i metodi @UiThread dai metodi @MainThread e viceversa. Tuttavia, è possibile che un thread dell'UI sia diverso dal thread principale, nel caso di app di sistema con più visualizzazioni su thread diversi. Pertanto, devi annotare i metodi associati alla gerarchia di oggetti View di un'app con @UiThread e annotare solo i metodi associati al ciclo di vita di un'app con @MainThread.

Se tutti i metodi di una classe condividono lo stesso requisito di threading, puoi aggiungere una singola annotazione di thread alla classe per verificare che tutti i metodi della classe vengano chiamati dallo stesso tipo di thread.

Un uso comune delle annotazioni dei thread è quello di convalidare che i metodi o le classi annotati con @WorkerThread vengano chiamati solo da un thread in background appropriato.

Annotazioni dei vincoli di valore

Utilizza le annotazioni @IntRange, @FloatRange e @Size per convalidare i valori dei parametri trasmessi. Sia @IntRange che @FloatRange sono più utili se applicati a parametri in cui è probabile che gli utenti sbaglino l'intervallo.

L'annotazione @IntRange verifica che un valore parametro intero o lungo rientri in un intervallo specificato. Il seguente esempio indica che il parametro alpha deve contenere un valore intero compreso tra 0 e 255:

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

public void