Linee guida per le API Android

Questa pagina ha lo scopo di fornire agli sviluppatori una guida per comprendere i principi generali che l'API Council applica nelle revisioni delle API.

Oltre a seguire queste linee guida durante la scrittura delle API, gli sviluppatori devono eseguire lo strumento API Lint, che codifica molte di queste regole nei controlli che esegue sulle API.

Consideralo come la guida alle regole rispettate da questo strumento Lint, oltre a consigli generali sulle regole che non possono essere codificate nello strumento con elevata precisione.

Strumento API Lint

API Lint è integrato nello strumento di analisi statica Metalava e viene eseguito automaticamente durante la convalida in CI. Puoi eseguirlo manualmente da un checkout della piattaforma locale utilizzando m checkapi o da un checkout AndroidX locale utilizzando ./gradlew :path:to:project:checkApi.

Regole API

La piattaforma Android e molte librerie Jetpack esistevano prima della creazione di questo insieme di linee guida e le norme stabilite più avanti in questa pagina sono in continua evoluzione per soddisfare le esigenze dell'ecosistema Android.

Di conseguenza, alcune API esistenti potrebbero non rispettare le linee guida. In altri casi, potrebbe offrire una migliore esperienza utente agli sviluppatori di app se una nuova API rimane coerente con le API esistenti anziché rispettare rigorosamente le linee guida.

Utilizza il tuo giudizio e contatta l'API Council se ci sono domande difficili su un'API che devono essere risolte o linee guida che devono essere aggiornate.

Nozioni di base sulle API

Questa categoria riguarda gli aspetti principali di un'API Android.

Tutte le API devono essere implementate

Indipendentemente dal pubblico di un'API (ad esempio, pubblico o @SystemApi), tutte le superfici API devono essere implementate quando vengono unite o esposte come API. Non unire gli stub API con l'implementazione in un secondo momento.

Le superfici API senza implementazioni presentano diversi problemi:

• Non è garantito che sia stata esposta una superficie adeguata o completa. Finché un'API non viene testata o utilizzata dai client, non è possibile verificare se un client dispone delle API appropriate per poter utilizzare la funzionalità.
• Le API senza implementazione non possono essere testate nelle anteprime per sviluppatori.
• Le API senza implementazione non possono essere testate in CTS.

Tutte le API devono essere testate

Ciò è in linea con i requisiti CTS della piattaforma, le norme AndroidX e, in generale, l'idea che le API devono essere implementate.

I test delle superfici API forniscono una garanzia di base che la superficie API sia utilizzabile e che abbiamo affrontato i casi d'uso previsti. Il test dell'esistenza non è sufficiente, deve essere testato il comportamento dell'API stessa.

Una modifica che aggiunge una nuova API deve includere i test corrispondenti nella stessa CL o nello stesso argomento Gerrit.

Le API devono anche essere testabili. Dovresti essere in grado di rispondere alla domanda: "Come testerà il codice che utilizza la tua API uno sviluppatore di app?"

Tutte le API devono essere documentate

La documentazione è una parte fondamentale dell'usabilità dell'API. Sebbene la sintassi di una superficie API possa sembrare ovvia, i nuovi client non comprenderanno la semantica, il comportamento o il contesto alla base dell'API.

Tutte le API generate devono essere conformi alle linee guida

Le API generate dagli strumenti devono seguire le stesse linee guida delle API del codice scritto a mano.

Strumenti sconsigliati per la generazione di API:

• AutoValue: viola le linee guida in vari modi, ad esempio non è possibile implementare classi di valori finali né builder finali con il funzionamento di AutoValue.

Stile di codice

Questa categoria riguarda lo stile di codice generale che gli sviluppatori devono utilizzare, soprattutto quando scrivono API pubbliche.

Segui le convenzioni di codifica standard, tranne dove indicato

Le convenzioni di codifica di Android sono documentate per i collaboratori esterni qui:

https://source.android.com/source/code-style.html

In generale, tendiamo a seguire le convenzioni di codifica standard di Java e Kotlin.

Gli acronimi non devono essere scritti in maiuscolo nei nomi dei metodi

Ad esempio, il nome del metodo deve essere runCtsTests e non runCTSTests.

I nomi non devono terminare con Impl

In questo modo vengono esposti i dettagli dell'implementazione, quindi evita di farlo.

Classi

Questa sezione descrive le regole relative a classi, interfacce ed ereditarietà.

Ereditare nuove classi pubbliche dalla classe base appropriata

L'ereditarietà espone elementi API nella sottoclasse che potrebbero non essere appropriati. Ad esempio, una nuova sottoclasse pubblica di FrameLayout ha l'aspetto di FrameLayout più i nuovi comportamenti e gli elementi API. Se l'API ereditata non è appropriata per il tuo caso d'uso, esegui l'ereditarietà da una classe più in alto nell'albero, ad esempio, ViewGroup o View.

Se sei tentato di eseguire l'override dei metodi della classe base per generare UnsupportedOperationException, riconsidera la classe base che stai utilizzando.

Utilizzare le classi di raccolte di base

Quando prendi una raccolta come argomento o la restituisci come valore, preferisci sempre la classe base all'implementazione specifica (ad esempio, restituisci List<Foo> anziché ArrayList<Foo>).

Utilizza una classe base che esprima vincoli appropriati per l'API. Ad esempio, utilizza List per un'API la cui raccolta deve essere ordinata e utilizza Set per un'API la cui raccolta deve essere costituita da elementi univoci.

In Kotlin, preferisci le raccolte immutabili. Per ulteriori dettagli, consulta la sezione Modificabilità della raccolta.

Classi astratte e interfacce

Java 8 aggiunge il supporto per i metodi di interfaccia predefiniti, che consentono ai progettisti di API di aggiungere metodi alle interfacce mantenendo la compatibilità binaria. Il codice della piattaforma e tutte le librerie Jetpack devono avere come target Java 8 o versioni successive.

Nei casi in cui l'implementazione predefinita è senza stato, i progettisti di API devono preferire le interfacce alle classi astratte, ovvero i metodi di interfaccia predefiniti possono essere implementati come chiamate ad altri metodi di interfaccia.

Nei casi in cui un costruttore o uno stato interno è richiesto dall'implementazione predefinita, devono essere utilizzate classi astratte.

In entrambi i casi, i progettisti di API possono scegliere di lasciare un singolo metodo astratto per semplificare l'utilizzo come lambda:

public interface AnimationEndCallback {
  // Always called, must be implemented.
  public void onFinished(Animation anim);
  // Optional callbacks.
  public default void onStopped(Animation anim) { }
  public default void onCanceled(Animation anim) { }
}

I nomi delle classi devono riflettere ciò che estendono

Ad esempio, le classi che estendono Service devono essere denominate FooService per chiarezza:

public class IntentHelper extends Service {}

public class IntentService extends Service {}

Suffissi generici

Evita di utilizzare suffissi generici per i nomi delle classi come Helper e Util per le raccolte di metodi di utilità. Inserisci invece i metodi direttamente nelle classi associate o nelle funzioni di estensione Kotlin.

Nei casi in cui i metodi collegano più classi, assegna alla classe contenitore un nome significativo che ne spieghi la funzione.

In casi molto limitati, l'utilizzo del suffisso Helper potrebbe essere appropriato:

• Utilizzato per la composizione del comportamento predefinito
• Potrebbe comportare la delega del comportamento esistente a nuove classi
• Potrebbe essere necessario uno stato persistente
• In genere, prevede View

Ad esempio, se le descrizioni comando di backporting richiedono di rendere persistente lo stato associato a un View e di chiamare diversi metodi su View per installare il backporting, TooltipHelper sarebbe un nome di classe accettabile.

Non esporre direttamente il codice generato da IDL come API pubbliche

Conserva il codice generato da IDL come dettagli di implementazione. Sono inclusi protobuf, socket, FlatBuffers o qualsiasi altra superficie API non Java e non NDK. Tuttavia, la maggior parte dell'IDL in Android è in AIDL, quindi questa pagina si concentra su AIDL.

Le classi AIDL generate non soddisfano i requisiti della guida di stile delle API (ad esempio, non possono utilizzare l'overload) e lo strumento AIDL non è progettato esplicitamente per mantenere la compatibilità delle API di linguaggio, pertanto non puoi incorporarle in un'API pubblica.

Aggiungi invece un livello API pubblico sopra l'interfaccia AIDL, anche se inizialmente è un wrapper superficiale.

Interfacce Binder

Se l'interfaccia Binder è un dettaglio di implementazione, può essere modificata liberamente in futuro, mentre il livello pubblico consente di mantenere la compatibilità con le versioni precedenti richiesta. Ad esempio, potresti dover aggiungere nuovi argomenti alle chiamate interne o ottimizzare il traffico IPC utilizzando il batching o lo streaming, la memoria condivisa o simili. Nessuna di queste operazioni può essere eseguita se la tua interfaccia AIDL è anche l'API pubblica.

Ad esempio, non esporre FooService direttamente come API pubblica:

// BAD: Public API generated from IFooService.aidl
public class IFooService {
   public void doFoo(String foo);
}

In alternativa, racchiudi l'interfaccia Binder all'interno di un gestore o di un'altra classe:

/**
 * @hide
 */
public class IFooService {
   public void doFoo(String foo);
}

public IFooManager {
   public void doFoo(String foo) {
      mFooService.doFoo(foo);
   }
}

Se in un secondo momento è necessario un nuovo argomento per questa chiamata, l'interfaccia interna può essere minimale e comode sovraccariche aggiunte all'API pubblica. Puoi utilizzare il livello di wrapping per gestire altri problemi di compatibilità con le versioni precedenti man mano che l'implementazione si evolve:

/**
 * @hide
 */
public class IFooService {
   public void doFoo(String foo, int flags);
}

public IFooManager {
   public void doFoo(String foo) {
      if (mAppTargetSdkLevel < 26) {
         useOldFooLogic(); // Apps targeting API before 26 are broken otherwise
         mFooService.doFoo(foo, FLAG_THAT_ONE_WEIRD_HACK);
      } else {
         mFooService.doFoo(foo, 0);
      }
   }

   public void doFoo(String foo, int flags) {
      mFooService.doFoo(foo, flags);
   }
}

Per le interfacce Binderche non fanno parte della piattaforma Android (ad esempio, un'interfaccia di servizio esportata da Google Play Services per l'utilizzo da parte delle app), il requisito di un'interfaccia IPC stabile, pubblicata e con controllo delle versioni significa che è molto più difficile far evolvere l'interfaccia stessa. Tuttavia, vale comunque la pena avere un livello wrapper intorno, per rispettare le altre linee guida dell'API e per semplificare l'utilizzo della stessa API pubblica per una nuova versione dell'interfaccia IPC, se dovesse mai diventare necessario.

Non utilizzare oggetti Binder non elaborati nell'API pubblica

Un oggetto Binder non ha alcun significato di per sé e pertanto non deve essere utilizzato nell'API pubblica. Un caso d'uso comune è utilizzare un Binder o un IBinder come token perché ha una semantica di identità. Anziché utilizzare un oggetto Binder non elaborato, utilizza una classe token wrapper.

public final class IdentifiableObject {
  public Binder getToken() {...}
}

public final class IdentifiableObjectToken {
  /**
   * @hide
   */
  public Binder getRawValue() {...}

  /**
   * @hide
   */
  public static IdentifiableObjectToken wrapToken(Binder rawValue) {...}
}

public final class IdentifiableObject {
  public IdentifiableObjectToken getToken() {...}
}

Le classi di gestione devono essere finali

Le classi di gestione devono essere dichiarate come final. Le classi di gestione comunicano con i servizi di sistema e sono l'unico punto di interazione. Non è necessaria alcuna personalizzazione, quindi dichiaralo come final.

Non utilizzare CompletableFuture o Future

java.util.concurrent.CompletableFuture ha un'ampia superficie API che consente la mutazione arbitraria del valore del futuro e ha valori predefiniti soggetti a errori .

Al contrario, java.util.concurrent.Future non dispone dell'ascolto non bloccante, il che rende difficile l'utilizzo con codice asincrono.

Nel codice della piattaforma e nelle API delle librerie di basso livello utilizzate sia da Kotlin che da Java, preferisci una combinazione di un callback di completamento, Executor e, se l'API supporta l'annullamento, CancellationSignal.

public void asyncLoadFoo(android.os.CancellationSignal cancellationSignal,
    Executor callbackExecutor,
    android.os.OutcomeReceiver<FooResult, Throwable> callback);

Se hai come target Kotlin, preferisci le funzioni suspend.

suspend fun asyncLoadFoo(): Foo

Nelle librerie di integrazione specifiche per Java, puoi utilizzare ListenableFuture di Guava.

public com.google.common.util.concurrent.ListenableFuture<Foo> asyncLoadFoo();

Non utilizzare Facoltativo

Sebbene Optional possa presentare vantaggi in alcune superfici API, non è coerente con l'area della superficie API Android esistente. @Nullable e @NonNull forniscono assistenza per gli strumenti per la sicurezza di null e Kotlin applica i contratti di nullabilità a livello di compilatore, rendendo Optional non necessario.

Per i primitivi facoltativi, utilizza i metodi accoppiati has e get. Se il valore non è impostato (has restituisce false), il metodo get deve generare un'eccezione IllegalStateException.

public boolean hasAzimuth() { ... }
public int getAzimuth() {
  if (!hasAzimuth()) {
    throw new IllegalStateException("azimuth is not set");
  }
  return azimuth;
}

Utilizzare costruttori privati per classi non istanziabili

Le classi che possono essere create solo da Builder, le classi contenenti solo costanti o metodi statici o classi non istanziabili devono includere almeno un costruttore privato per impedire l'istanziamento utilizzando il costruttore predefinito senza argomenti.

public final class Log {
  // Not instantiable.
  private Log() {}
}

Singleton

I singleton sono sconsigliati perché presentano i seguenti svantaggi relativi ai test:

1. La costruzione è gestita dalla classe, impedendo l'uso di falsi
2. I test non possono essere ermetici a causa della natura statica di un singleton
3. Per risolvere questi problemi, gli sviluppatori devono conoscere i dettagli interni del singleton o creare un wrapper intorno a esso.

Preferisci il pattern singola istanza, che si basa su una classe base astratta per risolvere questi problemi.

Singola istanza

Le classi a singola istanza utilizzano una classe base astratta con un costruttore private o internal e forniscono un metodo statico getInstance() per ottenere un'istanza. Il metodo getInstance() deve restituire lo stesso oggetto nelle chiamate successive.

L'oggetto restituito da getInstance() deve essere un'implementazione privata della classe base astratta.

class Singleton private constructor(...) {
  companion object {
    private val _instance: Singleton by lazy { Singleton(...) }

    fun getInstance(): Singleton {
      return _instance
    }
  }
}

abstract class SingleInstance private constructor(...) {
  companion object {
    private val _instance: SingleInstance by lazy { SingleInstanceImp(...) }
    fun getInstance(): SingleInstance {
      return _instance
    }
  }
}

L'istanza singola differisce dal singleton in quanto gli sviluppatori possono creare una versione fittizia di SingleInstance e utilizzare il proprio framework di inserimento delle dipendenze per gestire l'implementazione senza dover creare un wrapper oppure la libreria può fornire il proprio fake in un artefatto -testing.

Le classi che rilasciano risorse devono implementare AutoCloseable

Le classi che rilasciano risorse tramite close, release, destroy o metodi simili devono implementare java.lang.AutoCloseable per consentire agli sviluppatori di pulire automaticamente queste risorse quando utilizzano un blocco try-with-resources.

Evita di introdurre nuove sottoclassi View in android.*

Non introdurre nuove classi che ereditano direttamente o indirettamente da android.view.View nell'API pubblica della piattaforma (ovvero in android.*).

Il toolkit per la UI di Android ora è Compose-first. Le nuove funzionalità dell'interfaccia utente esposte dalla piattaforma devono essere esposte come API di livello inferiore che possono essere utilizzate per implementare Jetpack Compose e, facoltativamente, componenti UI basati su View per gli sviluppatori nelle librerie Jetpack. L'offerta di questi componenti nelle librerie offre opportunità per implementazioni di backporting quando le funzionalità della piattaforma non sono disponibili.

Campi

Queste regole riguardano i campi pubblici delle classi.

Non esporre i campi non elaborati

Le classi Java non devono esporre direttamente i campi. I campi devono essere privati e accessibili solo tramite getter e setter pubblici, indipendentemente dal fatto che questi campi siano finali o meno.

Rari casi includono strutture di dati di base in cui non è necessario migliorare il comportamento di specifica o recupero di un campo. In questi casi, i campi devono essere denominati utilizzando le convenzioni standard di denominazione delle variabili, ad esempio Point.x e Point.y.

Le classi Kotlin possono esporre proprietà.

I campi esposti devono essere contrassegnati come finali

I campi non elaborati sono fortemente sconsigliati (@see Non esporre campi non elaborati). Tuttavia, nella rara situazione in cui un campo viene esposto come campo pubblico, contrassegnalo con final.

I campi interni non devono essere esposti

Non fare riferimento ai nomi dei campi interni nell'API pubblica.

public int mFlags;

Utilizzare la modalità pubblica anziché quella protetta

@see Use public instead of protected

Costanti

Queste sono regole relative alle costanti pubbliche.

Le costanti flag non devono sovrapporsi ai valori int o long

Flag indica i bit che possono essere combinati in un valore di unione. In caso contrario, non chiamare la variabile o la costante flag.

public static final int FLAG_SOMETHING = 2;
public static final int FLAG_SOMETHING = 3;

public static final int FLAG_PRIVATE = 1 << 2;
public static final int FLAG_PRESENTATION = 1 << 3;

Per maggiori informazioni sulla definizione delle costanti dei flag pubblici, consulta @IntDef per i flag bitmask.

Le costanti final static devono utilizzare la convenzione di denominazione con tutte le lettere maiuscole e separate da trattini bassi

Tutte le parole nella costante devono essere scritte in maiuscolo e le parole multiple devono essere separate da _. Ad esempio:

public static final int fooThing = 5

public static final int FOO_THING = 5

Utilizzare i prefissi standard per le costanti

Molte delle costanti utilizzate in Android riguardano elementi standard, come flag, chiavi e azioni. Queste costanti devono avere prefissi standard per renderle più identificabili come tali.

Ad esempio, gli extra intent devono iniziare con EXTRA_. Le azioni di intent devono iniziare con ACTION_. Le costanti utilizzate con Context.bindService() devono iniziare con BIND_.

Nomi e ambiti delle costanti chiave

I valori delle costanti stringa devono essere coerenti con il nome della costante stessa e in genere devono essere limitati al pacchetto o al dominio. Ad esempio:

public static final String FOO_THING = "foo"

non è denominato in modo coerente né ha un ambito appropriato. In alternativa, valuta:

public static final String FOO_THING = "android.fooservice.FOO_THING"

I prefissi di android nelle costanti stringa con ambito sono riservati al progetto open source Android.

Le azioni e gli extra degli intent, nonché le voci del bundle, devono essere namespace utilizzando il nome del pacchetto in cui sono definiti.

package android.foo.bar {
  public static final String ACTION_BAZ = "android.foo.bar.action.BAZ"
  public static final String EXTRA_BAZ = "android.foo.bar.extra.BAZ"
}

Utilizzare la modalità pubblica anziché quella protetta

@see Use public instead of protected

Utilizzare prefissi coerenti

Tutte le costanti correlate devono iniziare con lo stesso prefisso. Ad esempio, per un insieme di costanti da utilizzare con i valori dei flag:

public static final int SOME_VALUE = 0x01;

public static final int SOME_OTHER_VALUE = 0x10;

public static final int SOME_THIRD_VALUE = 0x100;

public static final int FLAG_SOME_VALUE = 0x01;

public static final int FLAG_SOME_OTHER_VALUE = 0x10;

public static final int FLAG_SOME_THIRD_VALUE = 0x100;

@see Utilizzare i prefissi standard per le costanti

Utilizzare nomi delle risorse coerenti

Gli identificatori, gli attributi e i valori pubblici devono essere denominati utilizzando la convenzione di denominazione camelCase, ad esempio @id/accessibilityActionPageUp o @attr/textAppearance, in modo simile ai campi pubblici in Java.

In alcuni casi, un identificatore o un attributo pubblico include un prefisso comune separato da un trattino basso:

• Valori di configurazione della piattaforma come @string/config_recentsComponentName in config.xml
• Attributi di visualizzazione specifici del layout, ad esempio @attr/layout_marginStart in attrs.xml

I temi e gli stili pubblici devono seguire la convenzione di denominazione PascalCase gerarchica, ad esempio @style/Theme.Material.Light.DarkActionBar o @style/Widget.Material.SearchView.ActionBar, in modo simile alle classi nidificate in Java.

Le risorse di layout e disegnabili non devono essere esposte come API pubbliche. Se devono essere esposti, tuttavia, i layout e le risorse disegnabili pubblici devono essere denominati utilizzando la convenzione di denominazione under_score, ad esempio layout/simple_list_item_1.xml o drawable/title_bar_tall.xml.

Quando le costanti potrebbero cambiare, rendile dinamiche

Il compilatore potrebbe incorporare i valori costanti, quindi mantenere gli stessi valori è considerato parte del contratto API. Se il valore di una costante MIN_FOO o MAX_FOO potrebbe cambiare in futuro, valuta la possibilità di renderli metodi dinamici.

CameraManager.MAX_CAMERAS

CameraManager.getMaxCameras()

Considera la compatibilità futura per i callback

Le costanti definite nelle versioni future dell'API non sono note alle app che hanno come target API precedenti. Per questo motivo, le costanti fornite alle app devono tenere conto della versione API target dell'app e mappare le costanti più recenti a un valore coerente. Considera il seguente scenario:

Origine SDK ipotetica:

// Added in API level 22
public static final int STATUS_SUCCESS = 1;
public static final int STATUS_FAILURE = 2;
// Added in API level 23
public static final int STATUS_FAILURE_RETRY = 3;
// Added in API level 26
public static final int STATUS_FAILURE_ABORT = 4;

App ipotetica con targetSdkVersion="22":

if (result == STATUS_FAILURE) {
  // Oh no!
} else {
  // Success!
}

In questo caso, l'app è stata progettata entro i limiti del livello API 22 e ha fatto un'ipotesi (in qualche modo) ragionevole secondo cui esistevano solo due possibili stati. Se l'app riceve il nuovo STATUS_FAILURE_RETRY, lo interpreta come esito positivo.

I metodi che restituiscono costanti possono gestire in modo sicuro casi come questo limitando il loro output in modo che corrisponda al livello API di destinazione dell'app:

private int mapResultForTargetSdk(Context context, int result) {
  int targetSdkVersion = context.getApplicationInfo().targetSdkVersion;
  if (targetSdkVersion < 26) {
    if (result == STATUS_FAILURE_ABORT) {
      return STATUS_FAILURE;
    }
    if (targetSdkVersion < 23) {
      if (result == STATUS_FAILURE_RETRY) {
        return STATUS_FAILURE;
      }
    }
  }
  return result;
}

Gli sviluppatori non possono prevedere se un elenco di costanti potrebbe cambiare in futuro. Se definisci un'API con una costante UNKNOWN o UNSPECIFIED che sembra un catch-all, gli sviluppatori presumono che le costanti pubblicate quando hanno scritto la loro app siano esaustive. Se non vuoi impostare questa aspettativa, valuta se una costante generica è una buona idea per la tua API.

Inoltre, le librerie non possono specificare il proprio targetSdkVersion separato dall'app e la gestione delle modifiche al comportamento di targetSdkVersion dal codice della libreria è complicata e soggetta a errori.

Costante intera o stringa

Utilizza costanti intere e @IntDef se lo spazio dei nomi per i valori non è estensibile al di fuori del pacchetto. Utilizza costanti stringa se lo spazio dei nomi è condiviso o può essere esteso da codice al di fuori del pacchetto.

Classi di dati

Le classi di dati rappresentano un insieme di proprietà immutabili e forniscono un insieme piccolo e ben definito di funzioni di utilità per interagire con questi dati.

Non utilizzare data class nelle API Kotlin pubbliche, poiché il compilatore Kotlin non garantisce la compatibilità binaria o dell'API del linguaggio per il codice generato. In alternativa, implementa manualmente le funzioni richieste.

Creazione istanza

In Java, le classi di dati devono fornire un costruttore quando ci sono poche proprietà o utilizzare il pattern Builder quando ci sono molte proprietà.

In Kotlin, le classi di dati devono fornire un costruttore con argomenti predefiniti indipendentemente dal numero di proprietà. Le classi di dati definite in Kotlin potrebbero trarre vantaggio anche dalla fornitura di un builder quando si utilizzano client Java.

Modifica e copia

Nei casi in cui i dati devono essere modificati, fornisci una classe Builder con un costruttore di copia (Java) o una funzione membro copy() (Kotlin) che restituisce un nuovo oggetto.

Quando fornisci una funzione copy() in Kotlin, gli argomenti devono corrispondere al costruttore della classe e i valori predefiniti devono essere compilati utilizzando i valori correnti dell'oggetto:

class Typography(
  val labelMedium: TextStyle = TypographyTokens.LabelMedium,
  val labelSmall: TextStyle = TypographyTokens.LabelSmall
) {
    fun copy(
      labelMedium: TextStyle = this.labelMedium,
      labelSmall: TextStyle = this.labelSmall
    ): Typography = Typography(
      labelMedium = labelMedium,
      labelSmall = labelSmall
    )
}

Comportamenti aggiuntivi

Le classi di dati devono implementare sia equals() sia hashCode() e ogni proprietà deve essere presa in considerazione nelle implementazioni di questi metodi.

Le classi di dati possono implementare toString() con un formato consigliato che corrisponde all'implementazione della classe di dati di Kotlin, ad esempio User(var1=Alex, var2=42).

Metodi

Si tratta di regole relative a varie specifiche nei metodi, relative a parametri, nomi dei metodi, tipi restituiti e specificatori di accesso.

Tempo

Queste regole riguardano il modo in cui i concetti di tempo come date e durata devono essere espressi nelle API.

Preferisci i tipi java.time.*, se possibile

java.time.Duration, java.time.Instant e molti altri tipi di java.time.* sono disponibili in tutte le versioni della piattaforma tramite desugaring e devono essere preferiti quando si esprime l'ora nei parametri API o nei valori restituiti.

Preferisci esporre solo le varianti di un'API che accettano o restituiscono java.time.Duration o java.time.Instant e ometti le varianti primitive con lo stesso caso d'uso, a meno che il dominio API non sia uno in cui l'allocazione di oggetti nei pattern di utilizzo previsti avrebbe un impatto negativo sulle prestazioni.

I metodi che esprimono durate devono essere denominati duration

Se un valore temporale esprime la durata del tempo coinvolto, denomina il parametro "duration", non "time".

ValueAnimator.setTime(java.time.Duration);

ValueAnimator.setDuration(java.time.Duration);

Eccezioni:

"timeout" è appropriato quando la durata si applica specificamente a un valore di timeout.

"time" con il tipo java.time.Instant è appropriato quando si fa riferimento a un momento specifico nel tempo, non a una durata.

I metodi che esprimono durate o tempo come una primitiva devono essere denominati con la loro unità di tempo e utilizzare long

I metodi che accettano o restituiscono durate come primitive devono avere come suffisso del nome del metodo le unità di tempo associate (ad esempio Millis, Nanos, Seconds) per riservare il nome non decorato per l'utilizzo con java.time.Duration. Vedi Ora.

I metodi devono anche essere annotati in modo appropriato con l'unità e la base temporale:

• @CurrentTimeMillisLong: il valore è un timestamp non negativo misurato come il numero di millisecondi dal 1970-01-01T00:00:00Z.
• @CurrentTimeSecondsLong: il valore è un timestamp non negativo misurato come il numero di secondi trascorsi dal giorno 01/01/1970T00:00:00Z.
• @DurationMillisLong: il valore è una durata non negativa in millisecondi.
• @ElapsedRealtimeLong: il valore è un timestamp non negativo nella base temporale SystemClock.elapsedRealtime().
• @UptimeMillisLong: il valore è un timestamp non negativo nella base temporale SystemClock.uptimeMillis().

I parametri temporali primitivi o i valori restituiti devono utilizzare long, non int.

ValueAnimator.setDuration(@DurationMillisLong long);

ValueAnimator.setDurationNanos(long);

I metodi che esprimono unità di tempo devono preferire la notazione abbreviata non abbreviata per i nomi delle unità

public void setIntervalNs(long intervalNs);

public void setTimeoutUs(long timeoutUs);

public void setIntervalNanos(long intervalNanos);

public void setTimeoutMicros(long timeoutMicros);

Annotare argomenti di lungo periodo

La piattaforma include diverse annotazioni per fornire una digitazione più efficace per le unità di tempo di tipo long:

• @CurrentTimeMillisLong: il valore è un timestamp non negativo misurato come numero di millisecondi a partire da 1970-01-01T00:00:00Z, quindi nella base temporale System.currentTimeMillis().
• @CurrentTimeSecondsLong: il valore è un timestamp non negativo misurato come il numero di secondi trascorsi dal 1970-01-01T00:00:00Z.
• @DurationMillisLong: il valore è una durata non negativa in millisecondi.
• @ElapsedRealtimeLong: il valore è un timestamp non negativo nella base temporale SystemClock#elapsedRealtime().
• @UptimeMillisLong: il valore è un timestamp non negativo nella base temporale SystemClock#uptimeMillis().

Unità di misura

Per tutti i metodi che esprimono un'unità di misura diversa dal tempo, preferisci i prefissi delle unità SI in formato CamelCase.

public  long[] getFrequenciesKhz();

public  float getStreamVolumeDb();

Inserisci i parametri facoltativi alla fine degli overload

Se hai overload di un metodo con parametri facoltativi, mantieni questi parametri alla fine e mantieni un ordine coerente con gli altri parametri:

public int doFoo(boolean flag);

public int doFoo(int id, boolean flag);

public int doFoo(boolean flag);

public int doFoo(boolean flag, int id);

Quando aggiungi overload per gli argomenti facoltativi, il comportamento dei metodi più semplici deve essere esattamente lo stesso di quello dei metodi più elaborati a cui sono stati forniti argomenti predefiniti.

Corollario: non sovraccaricare i metodi se non per aggiungere argomenti facoltativi o per accettare diversi tipi di argomenti se il metodo è polimorfico. Se il metodo sovraccarico fa qualcosa di fondamentalmente diverso, assegnagli un nuovo nome.

I metodi con parametri predefiniti devono essere annotati con @JvmOverloads (solo Kotlin)

I metodi e i costruttori con parametri predefiniti devono essere annotati con @JvmOverloads per mantenere la compatibilità binaria.

Per saperne di più, consulta la sezione Function overloads for defaults nella guida ufficiale all'interoperabilità Kotlin-Java.

class Greeting @JvmOverloads constructor(
  loudness: Int = 5
) {
  @JvmOverloads
  fun sayHello(prefix: String = "Dr.", name: String) = // ...
}

Non rimuovere i valori dei parametri predefiniti (solo Kotlin)

Se un metodo è stato spedito con un parametro con un valore predefinito, la rimozione del valore predefinito è una modifica che causa interruzioni della compatibilità con le origini.

I parametri del metodo più distintivi e identificativi devono essere i primi

Se hai un metodo con più parametri, inserisci prima quelli più pertinenti. I parametri che specificano i flag e altre opzioni sono meno importanti di quelli che descrivono l'oggetto su cui viene eseguita l'azione. Se è presente un callback di completamento, inseriscilo per ultimo.

public void openFile(int flags, String name);

public void openFileAsync(OnFileOpenedListener listener, String name, int flags);

public void setFlags(int mask, int flags);

public void openFile(String name, int flags);

public void openFileAsync(String name, int flags, OnFileOpenedListener listener);

public void setFlags(int flags, int mask);

Vedi anche: Inserire i parametri facoltativi alla fine degli overload

Costruttori

Il pattern Builder è consigliato per la creazione di oggetti Java complessi ed è comunemente utilizzato in Android nei casi in cui:

• Le proprietà dell'oggetto risultante devono essere immutabili
• Esiste un numero elevato di proprietà obbligatorie, ad esempio molti argomenti del costruttore
• Esiste una relazione complessa tra le proprietà al momento della creazione, ad esempio è necessario un passaggio di verifica. Tieni presente che questo livello di complessità spesso indica problemi di usabilità dell'API.

Valuta se hai bisogno di un builder. I builder sono utili in una superficie API se vengono utilizzati per:

• Configura solo alcuni di un insieme potenzialmente ampio di parametri di creazione facoltativi
• Configura molti parametri di creazione facoltativi o obbligatori diversi, a volte di tipi simili o corrispondenti, in cui i siti di chiamata potrebbero altrimenti diventare confusi da leggere o soggetti a errori di scrittura
• Configura la creazione di un oggetto in modo incrementale, in cui diversi pezzi di codice di configurazione potrebbero effettuare chiamate al builder come dettagli di implementazione
• Consenti a un tipo di crescere aggiungendo parametri di creazione facoltativi aggiuntivi nelle versioni future dell'API

Se hai un tipo con tre o meno parametri obbligatori e nessun parametro facoltativo, puoi quasi sempre saltare un builder e utilizzare un costruttore semplice.

Le classi di origine Kotlin devono preferire i costruttori annotati con @JvmOverloads con argomenti predefiniti rispetto ai builder, ma possono scegliere di migliorare l'usabilità per i client Java fornendo anche i builder nei casi descritti in precedenza.

class Tone @JvmOverloads constructor(
  val duration: Long = 1000,
  val frequency: Int = 2600,
  val dtmfConfigs: List<DtmfConfig> = emptyList()
) {
  class Builder {
    // ...
  }
}

Le classi Builder devono restituire il builder

Le classi Builder devono abilitare l'incatenamento dei metodi restituendo l'oggetto Builder (ad esempio this) da ogni metodo, tranne build(). Gli oggetti integrati aggiuntivi devono essere passati come argomenti. Non restituire il builder di un altro oggetto. Ad esempio:

public static class Builder {
  public void setDuration(long);
  public void setFrequency(int);
  public DtmfConfigBuilder addDtmfConfig();
  public Tone build();
}

public class Tone {
  public static class Builder {
    public Builder setDuration(long);
    public Builder setFrequency(int);
    public Builder addDtmfConfig(DtmfConfig);
    public Tone build();
  }
}

Nei rari casi in cui una classe di base builder deve supportare l'estensione, utilizza un tipo restituito generico:

public abstract class Builder<T extends Builder<T>> {
  abstract T setValue(int);
}

public class TypeBuilder<T extends TypeBuilder<T>> extends Builder<T> {
  T setValue(int);
  T setTypeSpecificValue(long);
}

Le classi Builder devono essere create tramite un costruttore

Per mantenere una creazione coerente dei builder tramite la superficie API Android, tutti i builder devono essere creati tramite un costruttore e non un metodo di creazione statico. Per le API basate su Kotlin, Builder deve essere pubblico anche se gli utenti Kotlin devono fare affidamento implicitamente sul builder tramite un meccanismo di creazione in stile DSL/metodo factory. Le librerie non devono utilizzare @PublishedApi internal per nascondere selettivamente il costruttore della classe Builder dai client Kotlin.

public class Tone {
  public static Builder builder();
  public static class Builder {
  }
}

public class Tone {
  public static class Builder {
    public Builder();
  }
}

Tutti gli argomenti dei costruttori di builder devono essere obbligatori (ad esempio @NonNull)

Gli argomenti facoltativi, ad esempio @Nullable, devono essere spostati nei metodi setter. Il costruttore deve generare un'eccezione NullPointerException (valuta la possibilità di utilizzare Objects.requireNonNull) se non vengono specificati argomenti obbligatori.

Le classi Builder devono essere classi interne statiche finali dei tipi creati

Per una corretta organizzazione all'interno di un pacchetto, le classi builder devono in genere essere esposte come classi interne finali dei tipi creati, ad esempio Tone.Builder anziché ToneBuilder.

I builder possono includere un costruttore per creare una nuova istanza da una esistente

I builder possono includere un costruttore di copia per creare una nuova istanza del builder da un builder o un oggetto creato esistente. Non devono fornire metodi alternativi per creare istanze del builder da builder o oggetti di build esistenti.

public class Tone {
  public static class Builder {
    public Builder clone();
  }

  public Builder toBuilder();
}

public class Tone {
  public static class Builder {
    public Builder(Builder original);
    public Builder(Tone original);
  }
}

I setter del builder devono accettare argomenti @Nullable se il builder ha un costruttore di copia

Il ripristino è essenziale se è possibile creare una nuova istanza di un builder da un'istanza esistente. Se non è disponibile alcun costruttore di copia, il builder potrebbe avere argomenti @Nullable o @NonNullable.

public static class Builder {
  public Builder(Builder original);
  public Builder setObjectValue(@Nullable Object value);
}

I setter del builder possono accettare argomenti @Nullable per le proprietà facoltative

Spesso è più semplice utilizzare un valore Nullable per l'input di secondo grado, soprattutto in Kotlin, che utilizza argomenti predefiniti anziché builder e overload.

Inoltre, i setter @Nullable corrisponderanno ai getter, che devono essere @Nullable per le proprietà facoltative.

Value createValue(@Nullable OptionalValue optionalValue) {
  Value.Builder builder = new Value.Builder();
  if (optionalValue != null) {
    builder.setOptionalValue(optionalValue);
  }
  return builder.build();
}

Value createValue(@Nullable OptionalValue optionalValue) {
  return new Value.Builder()
    .setOptionalValue(optionalValue);
    .build();
}

// Or in other cases:

Value createValue() {
  return new Value.Builder()
    .setOptionalValue(condition ? new OptionalValue() : null);
    .build();
}

Utilizzo comune in Kotlin:

fun createValue(optionalValue: OptionalValue? = null) =
  Value.Builder()
    .apply { optionalValue?.let { setOptionalValue(it) } }
    .build()

fun createValue(optionalValue: OptionalValue? = null) =
  Value.Builder()
    .setOptionalValue(optionalValue)
    .build()

Il valore predefinito (se il setter non viene chiamato) e il significato di null devono essere documentati correttamente sia nel setter che nel getter.

/**
 * ...
 *
 * <p>Defaults to {@code null}, which means the optional value won't be used.
 */

I setter del builder possono essere forniti per le proprietà modificabili in cui sono disponibili setter nella classe integrata

Se la tua classe ha proprietà modificabili e richiede una classe Builder, chiediti innanzitutto se la tua classe deve effettivamente avere proprietà modificabili.

Successivamente, se hai la certezza di aver bisogno di proprietà modificabili, decidi quale dei seguenti scenari è più adatto al tuo caso d'uso previsto:

1. L'oggetto creato deve essere immediatamente utilizzabile, pertanto i setter devono essere forniti per tutte le proprietà pertinenti, modificabili o immutabili.

   map.put(key, new Value.Builder(requiredValue)
       .setImmutableProperty(immutableValue)
       .setUsefulMutableProperty(usefulValue)
       .build());
   

2. Potrebbe essere necessario effettuare alcune chiamate aggiuntive prima che l'oggetto creato possa essere utile, pertanto i setter non devono essere forniti per le proprietà modificabili.

   Value v = new Value.Builder(requiredValue)
       .setImmutableProperty(immutableValue)
       .build();
   v.setUsefulMutableProperty(usefulValue)
   Result r = v.performSomeAction();
   Key k = callSomeMethod(r);
   map.put(k, v);
   

Non mescolare i due scenari.

Value v = new Value.Builder(requiredValue)
    .setImmutableProperty(immutableValue)
    .setUsefulMutableProperty(usefulValue)
    .build();
Result r = v.performSomeAction();
Key k = callSomeMethod(r);
map.put(k, v);

I builder non devono avere getter

Il getter deve trovarsi nell'oggetto creato, non nel builder.

I setter del builder devono avere getter corrispondenti nella classe creata

public class Tone {
  public static class Builder {
    public Builder setDuration(long);
    public Builder setFrequency(int);
    public Builder addDtmfConfig(DtmfConfig);
    public Tone build();
  }
}

public class Tone {
  public static class Builder {
    public Builder setDuration(long);
    public Builder setFrequency(int);
    public Builder addDtmfConfig(DtmfConfig);
    public Tone build();
  }

  public long getDuration();
  public int getFrequency();
  public @NonNull List<DtmfConfig> getDtmfConfigs();
}

Denominazione del metodo builder

I nomi dei metodi del builder devono utilizzare lo stile setFoo(), addFoo() o clearFoo().

Le classi Builder devono dichiarare un metodo build()

Le classi builder devono dichiarare un metodo build() che restituisce un'istanza dell'oggetto costruito.

I metodi build() del builder devono restituire oggetti @NonNull

Il metodo build() di un builder deve restituire un'istanza non nulla dell'oggetto costruito. Nel caso in cui l'oggetto non possa essere creato a causa di parametri non validi, la convalida può essere posticipata al metodo di compilazione e deve essere generato un IllegalStateException.

Non esporre i blocchi interni

I metodi nell'API pubblica non devono utilizzare la parola chiave synchronized. Questa parola chiave fa sì che l'oggetto o la classe venga utilizzato come blocco e, poiché è esposto ad altri, potresti riscontrare effetti collaterali imprevisti se altro codice al di fuori della tua classe inizia a utilizzarlo per scopi di blocco.

Esegui invece qualsiasi blocco richiesto su un oggetto interno privato.

public synchronized void doThing() { ... }

private final Object mThingLock = new Object();

public void doThing() {
  synchronized (mThingLock) {
    ...
  }
}

I metodi in stile Accessor devono seguire le linee guida per le proprietà Kotlin

Se visualizzati dalle origini Kotlin, i metodi in stile accessore, ovvero quelli che utilizzano i prefissi get, set o is, saranno disponibili anche come proprietà Kotlin. Ad esempio, int getField() definito in Java è disponibile in Kotlin come proprietà val field: Int.

Per questo motivo e per soddisfare in generale le aspettative degli sviluppatori in merito al comportamento dei metodi di accesso, i metodi che utilizzano i prefissi dei metodi di accesso devono comportarsi in modo simile ai campi Java. Evita di utilizzare prefissi in stile funzione di accesso quando:

• Il metodo ha effetti collaterali. Preferisci un nome di metodo più descrittivo.
• Il metodo prevede un lavoro computazionalmente costoso. Preferisci compute
• Il metodo prevede il blocco o un altro lavoro a lunga esecuzione per restituire un valore, ad esempio IPC o altre operazioni di I/O. Preferisci fetch
• Il metodo blocca il thread finché non può restituire un valore. Preferisci await
• Il metodo restituisce una nuova istanza dell'oggetto a ogni chiamata. Preferisci create
• Il metodo potrebbe non restituire correttamente un valore. Preferisci request

Tieni presente che eseguire un'operazione costosa dal punto di vista computazionale una sola volta e memorizzare nella cache il valore per le chiamate successive viene comunque conteggiato come esecuzione di un'operazione costosa dal punto di vista computazionale. Il jank non viene ammortizzato tra i frame.

Utilizza il prefisso is per i metodi di accesso booleani

Si tratta della convenzione di denominazione standard per i metodi e i campi booleani in Java. In genere, i nomi di metodi e variabili booleani devono essere scritti come domande a cui risponde il valore restituito.

I metodi di accesso booleani Java devono seguire uno schema di denominazione set/is e i campi devono preferire is, ad esempio:

// Visibility is a direct property. The object "is" visible:
void setVisible(boolean visible);
boolean isVisible();

// Factory reset protection is an indirect property.
void setFactoryResetProtectionEnabled(boolean enabled);
boolean isFactoryResetProtectionEnabled();

final boolean isAvailable;

L'utilizzo di set/is per i metodi di accesso Java o di is per i campi Java consentirà di utilizzarli come proprietà da Kotlin:

obj.isVisible = true
obj.isFactoryResetProtectionEnabled = false
if (!obj.isAvailable) return

Le proprietà e i metodi di accesso devono in genere utilizzare una denominazione positiva, ad esempio Enabled anziché Disabled. L'utilizzo di una terminologia negativa inverte il significato di true e false e rende più difficile ragionare sul comportamento.

// Passing false here is a double-negative.
void setFactoryResetProtectionDisabled(boolean disabled);

Nei casi in cui il valore booleano descrive l'inclusione o la proprietà di una proprietà, puoi utilizzare has anziché is; tuttavia, questo non funziona con la sintassi delle proprietà Kotlin:

// Transient state is an indirect property used to track state
// related to the object. The object is not transient; rather,
// the object "has" transient state associated with it:
void setHasTransientState(boolean hasTransientState);
boolean hasTransientState();

Alcuni prefissi alternativi che potrebbero essere più adatti includono can e should:

// "Can" describes a behavior that the object may provide,
// and here is more concise than setRecordingEnabled or
// setRecordingAllowed. The object "can" record:
void setCanRecord(boolean canRecord);
boolean canRecord();

// "Should" describes a hint or property that is not strictly
// enforced, and here is more explicit than setFitWidthEnabled.
// The object "should" fit width:
void setShouldFitWidth(boolean shouldFitWidth);
boolean shouldFitWidth();

I metodi che attivano/disattivano comportamenti o funzionalità possono utilizzare il prefisso is e il suffisso Enabled:

// "Enabled" describes the availability of a property, and is
// more appropriate here than "can use" or "should use" the
// property:
void setWiFiRoamingSettingEnabled(boolean enabled)
boolean isWiFiRoamingSettingEnabled()

Analogamente, i metodi che indicano la dipendenza da altri comportamenti o funzionalità possono utilizzare il prefisso is e il suffisso Supported o Required:

// "Supported" describes whether this API would work on devices that support
// multiple users. The API "supports" multi-user:
void setMultiUserSupported(boolean supported)
boolean isMultiUserSupported()

// "Required" describes whether this API depends on devices that support
// multiple users. The API "requires" multi-user:
void setMultiUserRequired(boolean required)
boolean isMultiUserRequired()

In genere, i nomi dei metodi devono essere scritti come domande a cui risponde il valore restituito.

Metodi delle proprietà Kotlin

Per una proprietà di classe var foo: Foo Kotlin genererà metodi get/set utilizzando una regola coerente: anteponi get e metti in maiuscolo il primo carattere per il getter e anteponi set e metti in maiuscolo il primo carattere per il setter. La dichiarazione della proprietà produrrà metodi denominati public Foo getFoo() e public void setFoo(Foo foo), rispettivamente.

Se la proprietà è di tipo Boolean, si applica una regola aggiuntiva nella generazione del nome: se il nome della proprietà inizia con is, get non viene anteposto per il nome del metodo getter, ma viene utilizzato il nome della proprietà stesso. Pertanto, preferisci denominare le proprietà Boolean con un prefisso is per rispettare le linee guida per la denominazione:

var isVisible: Boolean

Se la tua proprietà rientra tra le eccezioni sopra menzionate e inizia con un prefisso appropriato, utilizza l'annotazione @get:JvmName sulla proprietà per specificare manualmente il nome appropriato:

@get:JvmName("hasTransientState")
var hasTransientState: Boolean

@get:JvmName("canRecord")
var canRecord: Boolean

@get:JvmName("shouldFitWidth")
var shouldFitWidth: Boolean

Funzioni di accesso alle maschere di bit

Consulta Utilizzare @IntDef per i flag bitmask per le linee guida dell'API relative alla definizione dei flag bitmask.

Setter

Devono essere forniti due metodi setter: uno che accetta una stringa di bit completa e sovrascrive tutti i flag esistenti e un altro che accetta una maschera di bit personalizzata per consentire una maggiore flessibilità.

/**
 * Sets the state of all scroll indicators.
 * <p>
 * See {@link #setScrollIndicators(int, int)} for usage information.
 *
 * @param indicators a bitmask of indicators that should be enabled, or
 *                   {@code 0} to disable all indicators
 * @see #setScrollIndicators(int, int)
 * @see #getScrollIndicators()
 */
public void setScrollIndicators(@ScrollIndicators int indicators);

/**
 * Sets the state of the scroll indicators specified by the mask. To change
 * all scroll indicators at once, see {@link #setScrollIndicators(int)}.
 * <p>
 * When a scroll indicator is enabled, it will be displayed if the view
 * can scroll in the direction of the indicator.
 * <p>
 * Multiple indicator types may be enabled or disabled by passing the
 * logical OR of the specified types. If multiple types are specified, they
 * will all be set to the same enabled state.
 * <p>
 * For example, to enable the top scroll indicator:
 * {@code setScrollIndicators(SCROLL_INDICATOR_TOP, SCROLL_INDICATOR_TOP)}
 * <p>
 * To disable the top scroll indicator:
 * {@code setScrollIndicators(0, SCROLL_INDICATOR_TOP)}
 *
 * @param indicators a bitmask of values to set; may be a single flag,
 *                   the logical OR of multiple flags, or 0 to clear
 * @param mask a bitmask indicating which indicator flags to modify
 * @see #setScrollIndicators(int)
 * @see #getScrollIndicators()
 */
public void setScrollIndicators(@ScrollIndicators int indicators, @ScrollIndicators int mask);

Getters

Per ottenere la maschera di bit completa, deve essere fornito un getter.

/**
 * Returns a bitmask representing the enabled scroll indicators.
 * <p>
 * For example, if the top and left scroll indicators are enabled and all
 * other indicators are disabled, the return value will be
 * {@code View.SCROLL_INDICATOR_TOP | View.SCROLL_INDICATOR_LEFT}.
 * <p>
 * To check whether the bottom scroll indicator is enabled, use the value
 * of {@code (getScrollIndicators() & View.SCROLL_INDICATOR_BOTTOM) != 0}.
 *
 * @return a bitmask representing the enabled scroll indicators
 */
@ScrollIndicators
public int getScrollIndicators();

Utilizzare la modalità pubblica anziché quella protetta

Preferisci sempre public a protected nell'API pubblica. L'accesso protetto alla fine risulta doloroso a lungo termine, perché gli implementatori devono eseguire l'override per fornire funzioni di accesso pubbliche nei casi in cui l'accesso esterno per impostazione predefinita sarebbe stato altrettanto valido.

Ricorda che la visibilità protectednon impedisce agli sviluppatori di chiamare un'API, ma la rende solo leggermente più fastidiosa.

Implementa nessuno o entrambi i metodi equals() e hashCode()

Se ne esegui l'override di uno, devi eseguire l'override anche dell'altro.

Implementa toString() per le classi di dati

È consigliabile che le classi di dati eseguano l'override di toString() per aiutare gli sviluppatori a eseguire il debug del codice.

Documenta se l'output è per il comportamento del programma o per il debug

Decidi se vuoi che il comportamento del programma si basi o meno sulla tua implementazione. Ad esempio, UUID.toString() e File.toString() documentano il formato specifico da utilizzare per i programmi. Se esponi informazioni solo per il debug, ad esempio Intent, allora implica l'ereditarietà dei documenti dalla superclasse.

Non includere informazioni aggiuntive

Tutte le informazioni disponibili da toString() devono essere disponibili anche tramite l'API pubblica dell'oggetto. In caso contrario, incoraggi gli sviluppatori ad analizzare e fare affidamento all'output toString(), il che impedirà modifiche future. Una buona prassi è implementare toString() utilizzando solo l'API pubblica dell'oggetto.

Scoraggiare l'affidamento all'output di debug

Sebbene sia impossibile impedire agli sviluppatori di fare affidamento all'output di debug, inclusa la System.identityHashCode del tuo oggetto nel suo output toString(), sarà molto improbabile che due oggetti diversi abbiano un output toString() uguale.

@Override
public String toString() {
  return getClass().getSimpleName() + "@" + Integer.toHexString(System.identityHashCode(this)) + " {mFoo=" + mFoo + "}";
}

Ciò può scoraggiare efficacemente gli sviluppatori dallo scrivere asserzioni di test come assertThat(a.toString()).isEqualTo(b.toString()) sui tuoi oggetti.

Utilizzare createFoo quando vengono restituiti oggetti appena creati

Utilizza il prefisso create, non get o new, per i metodi che creeranno valori di ritorno, ad esempio costruendo nuovi oggetti.

Quando il metodo crea un oggetto da restituire, indicalo chiaramente nel nome del metodo.

public FooThing getFooThing() {
  return new FooThing();
}

public FooThing createFooThing() {
  return new FooThing();
}

I metodi che accettano oggetti File devono accettare anche gli stream

Le posizioni di archiviazione dei dati su Android non sono sempre file su disco. Ad esempio, i contenuti trasferiti tra i confini degli utenti sono rappresentati come content:// Uri. Per attivare l'elaborazione di varie origini dati, le API che accettano oggetti File devono accettare anche InputStream, OutputStream o entrambi.

public void setDataSource(File file)
public void setDataSource(InputStream stream)

Prendi e restituisci primitive non elaborate anziché versioni in scatola

Se devi comunicare valori mancanti o nulli, valuta la possibilità di utilizzare -1, Integer.MAX_VALUE o Integer.MIN_VALUE.

public java.lang.Integer getLength()
public void setLength(java.lang.Integer)

public int getLength()
public void setLength(int value)

Evitare gli equivalenti di classe dei tipi primitivi evita l'overhead di memoria di queste classi, l'accesso ai valori dei metodi e, soprattutto, l'autoboxing che deriva dal casting tra tipi primitivi e di oggetti. Evitare questi comportamenti consente di risparmiare memoria e allocazioni temporanee che possono portare a costose e più frequenti operazioni di Garbage Collection.

Utilizza le annotazioni per chiarire i valori validi di parametri e restituiti

Sono state aggiunte annotazioni per gli sviluppatori per chiarire i valori consentiti in varie situazioni. In questo modo, gli strumenti possono aiutare più facilmente gli sviluppatori quando forniscono valori errati (ad esempio, quando trasmettono un int arbitrario quando il framework richiede uno di un insieme specifico di valori costanti). Utilizza una o tutte le seguenti annotazioni, se appropriate:

Supporto di valori Null

Le annotazioni di nullabilità esplicite sono richieste per le API Java, ma il concetto di nullabilità fa parte del linguaggio Kotlin e le annotazioni di nullabilità non devono mai essere utilizzate nelle API Kotlin.

@Nullable: indica che un determinato valore restituito, parametro o campo può essere nullo:

@Nullable
public String getName()

public void setName(@Nullable String name)

@NonNull: indica che un determinato valore restituito, parametro o campo non può essere null. La classificazione degli elementi come @Nullable è una funzionalità relativamente nuova di Android, pertanto la maggior parte dei metodi API di Android non è documentata in modo coerente. Pertanto, abbiamo uno stato a tre vie "sconosciuto, @Nullable, @NonNull", motivo per cui @NonNull fa parte delle linee guida per le API:

@NonNull
public String getName()

public void setName(@NonNull String name)

Per la documentazione della piattaforma Android, l'annotazione dei parametri del metodo genererà automaticamente la documentazione nella forma "Questo valore può essere nullo", a meno che "null" non venga utilizzato esplicitamente altrove nella documentazione dei parametri.

Metodi "non realmente annullabili" esistenti: i metodi esistenti nell'API senza un'annotazione @Nullable dichiarata possono essere annotati @Nullable se il metodo può restituire null in circostanze specifiche e ovvie (ad esempio findViewById()). Per gli sviluppatori che non vogliono eseguire il controllo di nullità, devono essere aggiunti metodi @NotNull requireFoo() complementari che generano IllegalArgumentException.

Metodi di interfaccia:le nuove API devono aggiungere l'annotazione corretta durante l'implementazione dei metodi di interfaccia, ad esempio Parcelable.writeToParcel() (ovvero, il metodo nella classe di implementazione deve essere writeToParcel(@NonNull Parcel, int), non writeToParcel(Parcel, int)); le API esistenti che non hanno le annotazioni non devono essere "corrette".

Applicazione della nullabilità

In Java, i metodi sono consigliati per eseguire la convalida dell'input per i parametri @NonNull utilizzando Objects.requireNonNull() e generare un NullPointerException quando i parametri sono nulli. Questa operazione viene eseguita automaticamente in Kotlin.

Risorse

Identificatori di risorse: i parametri interi che indicano gli ID per risorse specifiche devono essere annotati con la definizione del tipo di risorsa appropriata. Esiste un'annotazione per ogni tipo di risorsa, ad esempio @StringRes, @ColorRes e @AnimRes, oltre all'annotazione generica @AnyRes. Per esempio:

public void setTitle(@StringRes int resId)

@IntDef per i set di costanti

Costanti magiche:i parametri String e int che devono ricevere uno di un insieme finito di valori possibili indicati da costanti pubbliche devono essere annotati in modo appropriato con @StringDef o @IntDef. Queste annotazioni ti consentono di creare una nuova annotazione che puoi utilizzare come typedef per i parametri consentiti. Ad esempio:

/** @hide */
@IntDef(prefix = {"NAVIGATION_MODE_"}, value = {
  NAVIGATION_MODE_STANDARD,
  NAVIGATION_MODE_LIST,
  NAVIGATION_MODE_TABS
})
@Retention(RetentionPolicy.SOURCE)
public @interface NavigationMode {}

public static final int NAVIGATION_MODE_STANDARD = 0;
public static final int NAVIGATION_MODE_LIST = 1;
public static final int NAVIGATION_MODE_TABS = 2;

@NavigationMode
public int getNavigationMode();
public void setNavigationMode(@NavigationMode int mode);

I metodi sono consigliati per verificare la validità dei parametri annotati e generare un IllegalArgumentException se il parametro non fa parte del @IntDef

@IntDef per i flag bitmask

L'annotazione può anche specificare che le costanti sono flag e possono essere combinate con & e I:

/** @hide */
@IntDef(flag = true, prefix = { "FLAG_" }, value = {
  FLAG_USE_LOGO,
  FLAG_SHOW_HOME,
  FLAG_HOME_AS_UP,
})
@Retention(RetentionPolicy.SOURCE)
public @interface DisplayOptions {}

@StringDef per set di costanti stringa

Esiste anche l'annotazione @StringDef, che è esattamente come @IntDef nella sezione precedente, ma per le costanti String. Puoi includere più valori "prefix" che vengono utilizzati per generare automaticamente la documentazione per tutti i valori.

@SdkConstant per le costanti dell'SDK

@SdkConstant Annotate i campi pubblici quando sono uno di questi valori SdkConstant: ACTIVITY_INTENT_ACTION, BROADCAST_INTENT_ACTION, SERVICE_ACTION, INTENT_CATEGORY, FEATURE.

@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
public static final String ACTION_CALL = "android.intent.action.CALL";

Fornisci compatibilità con i valori null per gli override

Per la compatibilità delle API, l'annullabilità degli override deve essere compatibile con l'annullabilità attuale dell'elemento principale. La tabella seguente mostra le aspettative di compatibilità. In altre parole, gli override devono essere restrittivi o più restrittivi dell'elemento che sostituiscono.

Preferisci argomenti non nullabili (ad esempio @NonNull) ove possibile

Quando i metodi sono sovraccarichi, preferisci che tutti gli argomenti siano non nulli.

public void startActivity(@NonNull Component component) { ... }
public void startActivity(@NonNull Component component, @NonNull Bundle options) { ... }

Questa regola si applica anche ai setter di proprietà sovraccarichi. L'argomento principale deve essere non nullo e l'eliminazione della proprietà deve essere implementata come metodo separato. In questo modo si evitano chiamate "non sense" in cui lo sviluppatore deve impostare parametri finali anche se non sono obbligatori.

public void setTitleItem(@Nullable IconCompat icon, @ImageMode mode)
public void setTitleItem(@Nullable IconCompat icon, @ImageMode mode, boolean isLoading)

// Nonsense call to clear property
setTitleItem(null, MODE_RAW, false);

public void setTitleItem(@NonNull IconCompat icon, @ImageMode mode)
public void setTitleItem(@NonNull IconCompat icon, @ImageMode mode, boolean isLoading)
public void clearTitleItem()

Preferisci tipi restituiti non nullabili (ad esempio @NonNull) per i contenitori

Per i tipi di contenitori come Bundle o Collection, restituisci un contenitore vuoto e immutabile, se applicabile. Nei casi in cui null verrebbe utilizzato per distinguere la disponibilità di un contenitore, valuta la possibilità di fornire un metodo booleano separato.

@NonNull
public Bundle getExtras() { ... }

Le annotazioni di nullabilità per le coppie get e set devono corrispondere

Le coppie di metodi get e set per una singola proprietà logica devono sempre concordare nelle annotazioni di nullabilità. Se non segui questa linea guida, la sintassi delle proprietà di Kotlin non funzionerà e l'aggiunta di annotazioni di nullabilità in disaccordo ai metodi delle proprietà esistenti è quindi una modifica che interrompe la compatibilità con le origini per gli utenti Kotlin.

@NonNull
public Bundle getExtras() { ... }
public void setExtras(@NonNull Bundle bundle) { ... }

Valore restituito in caso di errore o guasto

Tutte le API devono consentire alle app di reagire agli errori. Restituire false, -1, null o altri valori generici di "si è verificato un errore" non fornisce a uno sviluppatore informazioni sufficienti sull'errore per gestire le aspettative degli utenti o monitorare con precisione l'affidabilità della propria app sul campo. Quando progetti un'API, immagina di creare un'app. Se si verifica un errore, l'API ti fornisce informazioni sufficienti per presentarlo all'utente o reagire in modo appropriato?

1. È consigliabile includere informazioni dettagliate in un messaggio di eccezione, ma gli sviluppatori non devono analizzarle per gestire l'errore in modo appropriato. Codici di errore dettagliati o altre informazioni devono essere esposti come metodi.
2. Assicurati che l'opzione di gestione degli errori scelta ti offra la flessibilità di introdurre nuovi tipi di errori in futuro. Per @IntDef, ciò significa includere un valore OTHER o UNKNOWN. Quando restituisci un nuovo codice, puoi controllare targetSdkVersion del chiamante per evitare di restituire un codice di errore che l'app non conosce. Per le eccezioni, utilizza una superclasse comune implementata dalle eccezioni, in modo che qualsiasi codice che gestisce quel tipo rilevi e gestisca anche i sottotipi.
3. Per uno sviluppatore dovrebbe essere difficile o impossibile ignorare per errore un errore. Se l'errore viene comunicato restituendo un valore, annota il metodo con @CheckResult.

Preferisci generare un ? extends RuntimeException quando viene raggiunta una condizione di errore o guasto a causa di un errore dello sviluppatore, ad esempio l'ignoranza dei vincoli sui parametri di input o la mancata verifica dello stato osservabile.

I metodi setter o di azione (ad esempio perform) possono restituire un codice di stato intero se l'azione potrebbe non riuscire a causa di condizioni o stati aggiornati in modo asincrono al di fuori del controllo dello sviluppatore.

I codici di stato devono essere definiti nella classe contenitore come campi public static final, con il prefisso ERROR_ ed enumerati in un'annotazione @hide @IntDef.

I nomi dei metodi devono sempre iniziare con il verbo, non con il soggetto

Il nome del metodo deve sempre iniziare con il verbo (ad esempio get, create, reload e così via), non con l'oggetto su cui stai agendo.

public void tableReload() {
  mTable.reload();
}

public void reloadTable() {
  mTable.reload();
}

Preferisci i tipi di raccolta agli array come tipo restituito o di parametro

Le interfacce di raccolta con tipi generici offrono diversi vantaggi rispetto agli array, tra cui contratti API più solidi in termini di unicità e ordinamento, supporto per i generici e una serie di metodi pratici per gli sviluppatori.

Eccezione per i tipi primitivi

Se gli elementi sono primitivi, preferisci gli array per evitare il costo del boxing automatico. Vedi Utilizzare e restituire primitive non elaborate anziché versioni in scatola

Eccezione per il codice sensibile alle prestazioni

In alcuni scenari, in cui l'API viene utilizzata in codice sensibile alle prestazioni (come API grafiche o di misurazione/layout/disegno), è accettabile utilizzare array anziché raccolte per ridurre le allocazioni e l'utilizzo della memoria.

Eccezione per Kotlin

Gli array Kotlin sono invarianti e il linguaggio Kotlin fornisce numerose API di utilità intorno agli array, quindi gli array sono alla pari con List e Collection per le API Kotlin destinate all'accesso da Kotlin.

Preferire le raccolte @NonNull

Preferisci sempre @NonNull per gli oggetti della raccolta. Quando restituisci una raccolta vuota, utilizza il metodo Collections.empty appropriato per restituire un oggetto raccolta a basso costo, con tipo corretto e immutabile.

Dove sono supportate le annotazioni di tipo, preferisci sempre @NonNull per gli elementi della raccolta.

Dovresti anche preferire @NonNull quando utilizzi array anziché raccolte (vedi elemento precedente). Se l'allocazione degli oggetti è un problema, crea una costante e passala, dopotutto un array vuoto è immutabile. Esempio:

private static final int[] EMPTY_USER_IDS = new int[0];

@NonNull
public int[] getUserIds() {
  int [] userIds = mService.getUserIds();
  return userIds != null ? userIds : EMPTY_USER_IDS;
}

Modificabilità della raccolta

Per impostazione predefinita, le API Kotlin devono preferire i tipi restituiti di sola lettura (non Mutable) per le raccolte, a meno che il contratto API non richieda specificamente un tipo restituito modificabile.

Le API Java, tuttavia, dovrebbero preferire i tipi restituiti modificabili per impostazione predefinita perché l'implementazione delle API Java della piattaforma Android non fornisce ancora un'implementazione conveniente delle raccolte immutabili. L'eccezione a questa regola sono i tipi di reso Collections.empty, che non sono modificabili. Nei casi in cui la mutabilità potrebbe essere sfruttata dai client, intenzionalmente o per errore, per interrompere il pattern di utilizzo previsto dell'API, le API Java devono prendere seriamente in considerazione la restituzione di una copia superficiale della raccolta.

@Nullable
public PermissionInfo[] getGrantedPermissions() {
  return mPermissions;
}

@NonNull
public Set<PermissionInfo> getGrantedPermissions() {
  if (mPermissions == null) {
    return Collections.emptySet();
  }
  return new ArraySet<>(mPermissions);
}

Tipi restituiti esplicitamente modificabili

Idealmente, le API che restituiscono raccolte non devono modificare l'oggetto raccolta restituito dopo la restituzione. Se la raccolta restituita deve essere modificata o riutilizzata in qualche modo, ad esempio una visualizzazione adattata di un set di dati modificabile, il comportamento preciso di quando i contenuti possono cambiare deve essere documentato esplicitamente o seguire le convenzioni di denominazione delle API consolidate.

/**
 * Returns a view of this object as a list of [Item]s.
 */
fun MyObject.asList(): List<Item> = MyObjectListWrapper(this)

La convenzione .asFoo() di Kotlin è descritta di seguito e consente alla raccolta restituita da .asList() di cambiare se la raccolta originale cambia.

Modificabilità degli oggetti del tipo di dati restituiti

Analogamente alle API che restituiscono raccolte, le API che restituiscono oggetti di tipo di dati idealmente non devono modificare le proprietà dell'oggetto restituito dopo la restituzione.

val tempResult = DataContainer()

fun add(other: DataContainer): DataContainer {
  tempResult.innerValue = innerValue + other.innerValue
  return tempResult
}

fun add(other: DataContainer): DataContainer {
  return DataContainer(innerValue + other.innerValue)
}

In casi estremamente limitati, alcuni codici sensibili alle prestazioni possono trarre vantaggio dal pooling o dal riutilizzo degli oggetti. Non scrivere la tua struttura di dati del pool di oggetti e non esporre gli oggetti riutilizzati nelle API pubbliche. In entrambi i casi, fai molta attenzione alla gestione dell'accesso simultaneo.

Utilizzo del tipo di parametro vararg

È consigliabile utilizzare le API Kotlin e Java vararg nei casi in cui lo sviluppatore creerebbe probabilmente un array nel sito di chiamata al solo scopo di passare più parametri correlati dello stesso tipo.

public void setFeatures(Feature[] features) { ... }

// Developer code
setFeatures(new Feature[]{Features.A, Features.B, Features.C});

public void setFeatures(Feature... features) { ... }

// Developer code
setFeatures(Features.A, Features.B, Features.C);

Copie difensive

Le implementazioni Java e Kotlin dei parametri vararg vengono compilate nello stesso bytecode basato su array e di conseguenza possono essere chiamate dal codice Java con un array modificabile. I progettisti di API sono fortemente incoraggiati a creare una copia superficiale difensiva del parametro array nei casi in cui verrà reso persistente in un campo o in una classe interna anonima.

public void setValues(SomeObject... values) {
   this.values = Arrays.copyOf(values, values.length);
}

Tieni presente che la creazione di una copia difensiva non fornisce alcuna protezione contro la modifica simultanea tra la chiamata al metodo iniziale e la creazione della copia, né protegge dalla mutazione degli oggetti contenuti nell'array.

Fornisci la semantica corretta con i parametri del tipo di raccolta o i tipi restituiti

List<Foo> è l'opzione predefinita, ma prendi in considerazione altri tipi per fornire un significato aggiuntivo:

• Utilizza Set<Foo> se la tua API è indifferente all'ordine degli elementi e non consente duplicati o i duplicati non hanno significato.

• Collection<Foo>, se la tua API è indifferente all'ordine e consente i duplicati.

Funzioni di conversione Kotlin

Kotlin utilizza spesso .toFoo() e .asFoo() per ottenere un oggetto di un tipo diverso da un oggetto esistente, dove Foo è il nome del tipo restituito della conversione. Ciò è coerente con la JDK Object.toString(). Kotlin fa un ulteriore passo avanti utilizzandolo per le conversioni primitive, ad esempio 25.toFloat().

La distinzione tra le conversioni denominate .toFoo() e .asFoo() è significativa:

Utilizza .toFoo() quando crei un nuovo oggetto indipendente

Come .toString(), una conversione "a" restituisce un nuovo oggetto indipendente. Se l'oggetto originale viene modificato in un secondo momento, il nuovo oggetto non rifletterà queste modifiche. Allo stesso modo, se l'oggetto nuovo viene modificato in un secondo momento, l'oggetto vecchio non rifletterà queste modifiche.

fun Foo.toBundle(): Bundle = Bundle().apply {
    putInt(FOO_VALUE_KEY, value)
}

Utilizza .asFoo() quando crei un wrapper dipendente, un oggetto decorato o un cast

Il casting in Kotlin viene eseguito utilizzando la parola chiave as. Riflette una modifica all'interfaccia, ma non all'identità. Se utilizzato come prefisso in una funzione di estensione, .asFoo() decora il destinatario. Una mutazione nell'oggetto ricevitore originale si rifletterà nell'oggetto restituito da asFoo(). Una mutazione nel nuovo oggetto Foo potrebbe essere riportata nell'oggetto originale.

fun <T> Flow<T>.asLiveData(): LiveData<T> = liveData {
    collect {
        emit(it)
    }
}

Le funzioni di conversione devono essere scritte come funzioni di estensione

La scrittura di funzioni di conversione al di fuori delle definizioni della classe del destinatario e del risultato riduce l'accoppiamento tra i tipi. Una conversione ideale richiede solo l'accesso all'API pubblica all'oggetto originale. Questo dimostra con un esempio che uno sviluppatore può scrivere conversioni analoghe anche per i propri tipi preferiti.

Genera eccezioni specifiche appropriate

I metodi non devono generare eccezioni generiche come java.lang.Exception o java.lang.Throwable, ma deve essere utilizzata un'eccezione specifica appropriata come java.lang.NullPointerException per consentire agli sviluppatori di gestire le eccezioni senza essere eccessivamente generici.

Gli errori non correlati agli argomenti forniti direttamente al metodo richiamato pubblicamente devono generare java.lang.IllegalStateException anziché java.lang.IllegalArgumentException o java.lang.NullPointerException.

Listener e callback

Queste sono le regole relative alle classi e ai metodi utilizzati per i meccanismi di listener e callback.

I nomi delle classi di callback devono essere al singolare

Utilizza MyObjectCallback anziché MyObjectCallbacks.

I nomi dei metodi di callback devono essere nel formato on

onFooEvent indica che FooEvent è in corso e che il callback deve agire di conseguenza.

Il tempo passato e presente deve descrivere il comportamento di temporizzazione

I metodi di callback relativi agli eventi devono essere denominati in modo da indicare se l'evento è già avvenuto o è in corso.

Ad esempio, se il metodo viene chiamato dopo l'esecuzione di un'azione di clic:

public void onClicked()

Tuttavia, se il metodo è responsabile dell'esecuzione dell'azione di clic:

public boolean onClick()

Registrazione del callback

Quando un listener o un callback può essere aggiunto o rimosso da un oggetto, i metodi associati devono essere denominati add e remove o register e unregister. Rispetta la convenzione esistente utilizzata dal corso o da altri corsi dello stesso pacchetto. Quando non esiste un precedente, preferisci l'aggiunta e la rimozione.

I metodi che prevedono la registrazione o l'annullamento della registrazione dei callback devono specificare il nome completo del tipo di callback.

public void addFooCallback(@NonNull FooCallback callback);
public void removeFooCallback(@NonNull FooCallback callback);

public void registerFooCallback(@NonNull FooCallback callback);
public void unregisterFooCallback(@NonNull FooCallback callback);

Evita i getter per i callback

Non aggiungere metodi getFooCallback(). Si tratta di una soluzione di emergenza allettante per i casi in cui gli sviluppatori potrebbero voler concatenare un callback esistente con la propria sostituzione, ma è fragile e rende difficile ragionare sullo stato attuale per gli sviluppatori di componenti. Ad esempio,

• Lo sviluppatore A chiama il numero setFooCallback(a)
• Lo sviluppatore B chiama setFooCallback(new B(getFooCallback()))
• Lo sviluppatore A vuole rimuovere il proprio callback a e non ha modo di farlo senza conoscere il tipo di B e senza che B sia stato creato per consentire tali modifiche al callback di wrapping.

Accetta l'esecutore per controllare l'invio del callback

Quando registri callback che non hanno aspettative di threading esplicite (praticamente ovunque al di fuori del toolkit UI), ti consigliamo vivamente di includere un parametro Executor come parte della registrazione per consentire allo sviluppatore di specificare il thread su cui verranno richiamati i callback.

public void registerFooCallback(
    @NonNull @CallbackExecutor Executor executor,
    @NonNull FooCallback callback)

/**
 * ...
 * Note that the callback will be executed on the main thread using
 * {@link Looper.getMainLooper()}. To specify the execution thread, use
 * {@link registerFooCallback(Executor, FooCallback)}.
 * ...
 */
public void registerFooCallback(
    @NonNull FooCallback callback)

public void registerFooCallback(
    @NonNull @CallbackExecutor Executor executor,
    @NonNull FooCallback callback)

public class SynchronousExecutor implements Executor {
    @Override
    public void execute(Runnable r) {
        r.run();
    }
}

public void setFooCallback(
    @NonNull @CallbackExecutor Executor executor,
    @NonNull FooCallback callback)

public void clearFooCallback()

registerThing(Thing)

unregisterThing(Thing)

class RequestParameters {
  public int getId() { ... }
}

class RequestExecutor {
  public void executeRequest(
    RequestParameters parameters,
    Consumer<RequestParameters> onRequestCompletedListener) { ... }
}

public interface MostlyOptionalCallback {
  void onImportantAction();
  default void onOptionalInformation() {
    // Empty stub, this method is optional.
  }
}

interface FooType {
  // Before:
  public FooResult requestFoo(FooRequest request);

  // After:
  public void requestFooAsync(FooRequest request, Executor executor,
      OutcomeReceiver<FooResult, Throwable> callback);
}

suspend fun FooType.requestFoo(request: FooRequest): FooResult =
  suspendCancellableCoroutine { continuation ->
    requestFooAsync(request, Runnable::run, continuation.asOutcomeReceiver())
  }

public void schedule(Runnable runnable)

public void schedule(int delay, Runnable runnable)

/**
 * Returns the priority of the thread.
 */
@IntRange(from = 1, to = 10)
public int getPriority() { ... }

public static final int FOO = 0;
public static final int BAR = 1;

/**
 * Sets value to one of FOO or <code>BAR</code>.
 *
 * @param value the value being set, one of FOO or BAR
 */
public void setValue(int value) { ... }

/**
 * Sets value to one of {@link #FOO} or {@link #BAR}.
 *
 * @param value the value being set
 */
public void setValue(@ValueType int value) { ... }

/**
 * @param e The element to be appended to the list. This must not be
 *       null. If the list contains no entries, this element will
 *       be added at the beginning.
 * @return This method returns true on success.
 */

/**
 * @param e element to be appended to this list, must be non-{@code null}
 * @return {@code true} on success, {@code false} otherwise
 */

/**
 * ...
 * @throws IOException If it cannot find the schema for {@code toVersion}
 * @throws IllegalStateException If the schema validation fails
 */
public SupportSQLiteDatabase runMigrationsAndValidate(String name, int version,
    boolean validateDroppedTables, Migration... migrations) throws IOException {
  // ...
  if (!dbPath.exists()) {
    throw new IllegalStateException("Cannot find the database file for " + name
        + ". Before calling runMigrations, you must first create the database "
        + "using createDatabase.");
  }
  // ...

/**
 * ...
 * @throws IOException If something goes wrong reading the file, such as a bad
 *                     database header or missing permissions
 */
@Throws(IOException::class)
fun readVersion(databaseFile: File): Int {
  // ...
  val read = input.read(buffer)
    if (read != 4) {
      throw IOException("Bad database header, unable to read 4 bytes at " +
          "offset 60")
    }
  }
  // ...

try {
    ...
} catch (RemoteException e) {
    throw e.rethrowFromSystemServer();
}

/**
 * Constructs a shallow copy of {@code other}.
 */
public Foo(Foo other)

public class Foo {
    public static final class Builder {
        /**
         * Constructs a Foo builder using data from {@code other}.
         */
        public Builder(Foo other)

@RestrictTo(RestrictTo.Scope.LIBRARY)
@Retention(RetentionPolicy.SOURCE)
@IntDef({
  STREAM_TYPE_FULL_IMAGE_DATA,
  STREAM_TYPE_EXIF_DATA_ONLY,
})
public @interface ExifStreamType {}

class FooManager {
  Context mContext;

  void fooBar() {
    mIFooBar.fooBarForUser(mContext.getUser());
  }
}

class FooManager {
  Context mContext;

  Foobar getFoobar() {
    // Bad: doesn't appy mContext.getUserId().
    mIFooBar.fooBarForUser(Process.myUserHandle());
  }

  Foobar getFoobar() {
    // Also bad: doesn't appy mContext.getUserId().
    mIFooBar.fooBar();
  }

  Foobar getFoobarForUser(UserHandle user) {
    mIFooBar.fooBarForUser(user);
  }
}

Foobar getFoobarForUser(UserHandle user);

Foobar getFoobarForUser(int userId);

Foobar getFoobarForUser(@UserIdInt int user);

companion object {
  @JvmField val BIG_INTEGER_ONE = BigInteger.ONE
  @JvmStatic fun fromPointF(pointf: PointF) {
    /* ... */
  }
}

/**
 * Simple version of ...
 *
 * @deprecated Use the {@link androidx.fragment.app.DialogFragment}
 *             class with {@link androidx.fragment.app.FragmentManager}
 *             instead.
 */
@Deprecated
public final void showDialog(int id)

<!-- Attribute whether the accessibility service ...
     {@deprecated Not used by the framework}
 -->
<attr name="canRequestEnhancedWebAccessibility" format="boolean" />

/**
 * ...
 * @deprecated Use {@link #doThing(int, Bundle)} instead.
 */
@Deprecated
public void doThing(int action) {
  ...
}

public void doThing(int action, @Nullable Bundle extras) {
  ...
}

/**
 * ...
 * @deprecated No longer displayed in the status bar as of API 21.
 */
@Deprecated
public RemoteViews tickerView;

/**
 * Ringer volume. This is ...
 *
 * @removed Not functional since API 2.
 */
public static final String VOLUME_RING = ...

@Discouraged(message = "Use of this function is discouraged because resource
                        reflection makes it harder to perform build
                        optimizations and compile-time verification of code. It
                        is much more efficient to retrieve resources by
                        identifier (such as `R.foo.bar`) than by name (such as
                        `getIdentifier()`)")
public int getIdentifier(String name, String defType, String defPackage) {
    return mResourcesImpl.getIdentifier(name, defType, defPackage);
}

import android.app.compat.CompatChanges;
import android.compat.annotation.ChangeId;
import android.compat.annotation.EnabledSince;

public class MyClass {
  @ChangeId
  // This means the change will be enabled for target SDK R and higher.
  @EnabledSince(targetSdkVersion=android.os.Build.VERSION_CODES.R)
  // Use a bug number as the value, provide extra detail in the bug.
  // FOO_NOW_DOES_X will be the change name, and 123456789 the change ID.
  static final long FOO_NOW_DOES_X = 123456789L;

  public void doFoo() {
    if (CompatChanges.isChangeEnabled(FOO_NOW_DOES_X)) {
      // do the new thing
    } else {
      // do the old thing
    }
  }
}

<xs:element name="foo">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="name" type="xs:string">
                <xs:annotation name="Deprecated"/>
            </xs:element>
        </xs:sequence>
    </xs:complexType>
</xs:element>

<!-- Original "sequence" value -->
<xs:element name="foo">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="name" type="xs:string">
                <xs:annotation name="Deprecated"/>
            </xs:element>
        </xs:sequence>
    </xs:complexType>
</xs:element>

<!-- New "choice" value -->
<xs:element name="fooChoice">
    <xs:complexType>
        <xs:choice>
            <xs:element name="name" type="xs:string"/>
        </xs:choice>
    </xs:complexType>
</xs:element>

<permission
    android:name="com.android.permissioncontroller.permission.MANAGE_ROLES_FROM_CONTROLLER"
    android:protectionLevel="signature" />

<permission
    android:name="android.permission.health.READ_ACTIVE_CALORIES_BURNED"
    android:label="@string/active_calories_burned_read_content_description"
    android:protectionLevel="dangerous"
    android:permissionGroup="android.permission-group.HEALTH" />