Android API guidelines

Stay organized with collections Save and categorize content based on your preferences.

This page is intended to be a guide for developers to understand the general principles that the API Council enforces in API reviews.

In addition to following these guidelines when writing APIs, developers should run the API Lint tool, which encodes many of these rules in checks that it runs against APIs.

Think of this as the guide to the rules that are obeyed by that Lint tool, plus general advice on rules that can't be codified into that tool with high accuracy.

API Lint tool

API Lint is integrated into the Metalava static analysis tool and runs automatically during validation in CI. You can run it manually from a local platform checkout using m checkapi or a local AndroidX checkout using ./gradlew :path:to:project:checkApi.

API rules

The Android platform and many Jetpack libraries existed before this set of guidelines was created, and the policies set forth later in this page are continually evolving to meet the needs of the Android ecosystem.

As a result, some existing APIs may not follow the guidelines. In other cases, it might provide a better user experience for app developers if a new API stays consistent with existing APIs rather than strictly adhere to the guidelines.

Use your judgement and reach out to API Council if there are difficult questions about an API that need to be resolved or guidelines that need to be updated.

API basics

This category pertains to the core aspects of an Android API.

All APIs must be implemented

Irrespective of an API's audience (for example, public or @SystemApi), all API surfaces must be implemented when merged or exposed as API. Don't merge API stubs with implementation to come at a later date.

API surfaces without implementations have multiple issues:

• There is no guarantee that a proper or complete surface has been exposed. Until an API is tested or used by clients, there is no way to verify a client has the appropriate APIs to be able to use the feature.
• APIs without implementation can't be tested in Developer Previews.
• APIs without implementation can't be tested in CTS.

All APIs must be tested

This is in line with platform CTS requirements, AndroidX policies, and generally the idea that APIs must be implemented.

Testing API surfaces provides a base guarantee that the API surface is usable and we have addressed expected use cases. Testing for existence isn't sufficient; the behavior of the API itself must be tested.

A change that adds a new API should include corresponding tests in the same CL or Gerrit topic.

APIs should also be testable. You should be able to answer the question, "How will an app developer test code that uses your API?"

All APIs must be documented

Documentation is a key part of API usability. While the syntax of an API surface may seem obvious, any new clients won't understand the semantics, behavior, or context behind the API.

All generated APIs must be compliant with the guidelines

APIs generated by tools must follow the same API guidelines as hand-written code.

Tools that are discouraged for generating APIs:

• AutoValue: violates guidelines in various ways, for example, there is no way to implement final value classes nor final builders with the way AutoValue works.

Code style

This category pertains to the general code style that developers should use, especially when writing public APIs.

Follow standard coding conventions, except where noted

Android coding conventions are documented for external contributors here:

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

Overall, we tend to follow standard Java and Kotlin coding conventions.

Acronyms shouldn't be capitalized in method names

For example: method name should be runCtsTests and not runCTSTests.

Names shouldn't end with Impl

This exposes implementation details, avoid that.

Classes

This section describes rules about classes, interfaces, and inheritance.

Inherit new public classes from the appropriate base class

Inheritance exposes API elements in your subclass that might not be appropriate. For example, a new public subclass of FrameLayout looks like FrameLayout plus the new behaviors and API elements. If that inherited API isn't appropriate for your use case, inherit from a class further up the tree, for example, ViewGroup or View.

If you're tempted to override methods from the base class to throw UnsupportedOperationException, reconsider which base class you're using.

Use the base collections classes

Whether taking a collection as an argument or returning it as a value, always prefer the base class over the specific implementation (such as return List<Foo> rather than ArrayList<Foo>).

Use a base class that expresses appropriate constraints for the API. For example, use List for an API whose collection must be ordered, and use Set for an API whose collection must consist of unique elements.

In Kotlin, prefer immutable collections. See Collection mutability for more details.

Abstract classes versus interfaces

Java 8 adds support for default interface methods, which allows API designers to add methods to interfaces while maintaining binary compatibility. Platform code and all Jetpack libraries should target Java 8 or later.

In cases where the default implementation is stateless, API designers should prefer interfaces over abstract classes -- that is, default interface methods can be implemented as calls to other interface methods.

In cases where a constructor or internal state is required by the default implementation, abstract classes must be used.

In both cases, API designers can choose to leave a single method abstract to simplify usage as a 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) { }
}

Class names should reflect what they extend

For example, classes that extend Service should be named FooService for clarity:

public class IntentHelper extends Service {}

public class IntentService extends Service {}

Generic suffixes

Avoid using generic class name suffixes like Helper and Util for collections of utility methods. Instead, put the methods directly in the associated classes or into Kotlin extension functions.

In cases where methods are bridging multiple classes, give the containing class a meaningful name that explains what it does.

In very limited cases, using the Helper suffix might be appropriate:

• Used for composition of default behavior
• Might involve delegation of existing behavior to new classes
• Might require persisted state
• Typically involves View

For example, if backporting tooltips requires persisting the state associated with a View and calling several methods on the View to install the backport, TooltipHelper would be an acceptable class name.

Don't expose IDL-generated code as public APIs directly

Keep IDL-generated code as implementation details. This includes protobuf, sockets, FlatBuffers, or any other non-Java, non-NDK API surface. However, most IDL in Android is in AIDL, so this page focuses on AIDL.

Generated AIDL classes don't meet the API style guide requirements (for example, they can't use overloading) and the AIDL tool isn't explicitly designed to maintain language API compatibility, so you can't embed them in a public API.

Instead, add a public API layer on top of the AIDL interface, even if it initially is a shallow wrapper.

Binder interfaces

If the Binder interface is an implementation detail, it can be changed freely in the future, with the public layer allowing for the required backward compatibility to be maintained. For example, you might need to add new arguments to the internal calls, or optimize IPC traffic by using batching or streaming, using shared memory, or similar. None of these can be done if your AIDL interface is also the public API.

For example, don't expose FooService as a public API directly:

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

Instead, wrap the Binder interface inside a manager or other class:

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

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

If later a new argument is needed for this call, the internal interface can be minimal and convenient overloads added to the public API. You can use the wrapping layer to handle other backward-compatibility concerns as the implementation evolves:

/**
 * @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);
   }
}

For Binder interfaces that aren't part of the Android platform (for example, a service interface exported by Google Play services for apps to use), the requirement for a stable, published, and versioned IPC interface means that it's much harder to evolve the interface itself. However, it's still worthwhile to have a wrapper layer around it, to match other API guidelines and to make it easier to use the same public API for a new version of the IPC interface, if that ever becomes necessary.

Don't use raw Binder objects in public API

A Binder object doesn't have any meaning on its own and thus shouldn't be used in public API. One common use case is to use a Binder or IBinder as a token because it has identity semantics. Instead of using a raw Binder object use a wrapper token class instead.

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

Manager classes must be final

Manager classes should be declared as final. Manager classes talk to system services and are the single point of interaction. There is no need for customization so declare it as final.

Don't use CompletableFuture or Future

java.util.concurrent.CompletableFuture has a large API surface that permits arbitrary mutation of the future's value and has error-prone defaults .

Conversely, java.util.concurrent.Future is missing nonblocking listening, making it hard to use with asynchronous code.

In platform code and low-level library APIs consumed by both Kotlin and Java, prefer a combination of a completion callback, Executor, and if the API supports cancellation CancellationSignal.

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

If you're targeting Kotlin, prefer suspend functions.

suspend fun asyncLoadFoo(): Foo

In Java-specific integration libraries, you can use Guava's ListenableFuture.

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

Don't use Optional

While Optional can have advantages in some API surfaces, it's inconsistent with the existing Android API surface area. @Nullable and @NonNull provide tooling assistance for null safety and Kotlin enforces nullability contracts at the compiler level, making Optional unnecessary.

For optional primitives, use paired has and get methods. If the value isn't set (has returns false), the get method should throw an IllegalStateException.

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

Use private constructors for noninstantiable classes

Classes that can only be created by Builders, classes containing only constants or static methods, or otherwise noninstantiable classes should include at least one private constructor to prevent instantiation using the default no-arg constructor.

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

Singletons

Singleton are discouraged because they have the following testing-related drawbacks:

1. Construction is managed by the class, preventing the use of fakes
2. Tests can't be hermetic due to the static nature of a singleton
3. To work around these issues, developers either have to know the internal details of the singleton or create a wrapper around it

Prefer the single instance pattern, which relies on an abstract base class to address these issues.

Single instance

Single instance classes use an abstract base class with a private or internal constructor and provide a static getInstance() method to obtain an instance. The getInstance() method must return the same object on subsequent calls.

The object returned by getInstance() should be a private implementation of the abstract base class.

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
    }
  }
}

Single instance differs from singleton in that developers can create a fake version of SingleInstance and use their own Dependency Injection framework to manage the implementation without having to create a wrapper, or the library can provide its own fake in a -testing artifact.

Classes that release resources should implement AutoCloseable

Classes that release resources through close, release, destroy or similar methods should implement java.lang.AutoCloseable to allow developers to automatically clean up these resources when using a try-with-resources block.

Avoid introducing new View subclasses in android.*

Don't introduce new classes that inherit directly or indirectly from android.view.View in the platform public API (that is, in android.*).

Android's UI toolkit is now Compose-first. New UI features exposed by the platform should be exposed as lower-level APIs that can be used to implement Jetpack Compose and optionally View-based UI components for developers in Jetpack libraries. Offering these components in libraries affords opportunities for backported implementations when platform features are not available.

Fields

These rules are about public fields on classes.

Don't expose raw fields

Java classes shouldn't expose fields directly. Fields should be private and accessible only using public getters and setters regardless of whether these fields are final or not.

Rare exceptions include basic data structures where there is no need to enhance behavior of specifying or retrieving a field. In such cases, the fields should be named using standard variable naming conventions, for example, Point.x and Point.y.

Kotlin classes can expose properties.

Exposed fields should be marked final

Raw fields are strongly discouraged (@see Don't expose raw fields). But in the rare situation where a field is exposed as a public field, mark that field final.

Internal fields shouldn't be exposed

Don't reference internal field names in public API.

public int mFlags;

Use public instead of protected

@see Use public instead of protected

Constants

These are rules about public constants.

Flag constants shouldn't overlap int or long values

Flags implies bits that can be combined into some union value. If this isn't the case, don't call the variable or constant 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;

See @IntDef for bitmask flags for more information on defining public flag constants.

static final constants should use all-cap, underscore-separated naming convention

All words in the constant should be capitalized and multiple words should be separated by _. For example:

public static final int fooThing = 5

public static final int FOO_THING = 5

Use standard prefixes for constants

Many of the constants used in Android are for standard things, such as flags, keys, and actions. These constants should have standard prefixes to make them more identifiable as these things.

For example, intent extras should start with EXTRA_. Intent actions should start with ACTION_. Constants used with Context.bindService() should start with BIND_.

Key constant names and scopes

String constant values should be consistent with the constant name itself, and should generally be scoped to the package or domain. For example:

public static final String FOO_THING = "foo"

is neither named consistently nor appropriately scoped. Instead, consider:

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

Prefixes of android in scoped string constants are reserved for the Android Open Source Project.

Intent actions and extras, as well as Bundle entries, should be namespaced using the package name they are defined within.

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"
}

Use public instead of protected

@see Use public instead of protected

Use consistent prefixes

Related constants should all start with the same prefix. For example, for a set of constants to use with flag values:

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 Use standard prefixes for constants

Use consistent resource names

Public identifiers, attributes, and values must be named using the camelCase naming convention, for example @id/accessibilityActionPageUp or @attr/textAppearance, similar to public fields in Java.

In some cases, a public identifier or attribute includes a common prefix separated by an underscore:

• Platform config values such as @string/config_recentsComponentName in config.xml
• Layout-specific view attributes such as @attr/layout_marginStart in attrs.xml

Public themes and styles must follow the hierarchical PascalCase naming convention, for example @style/Theme.Material.Light.DarkActionBar or @style/Widget.Material.SearchView.ActionBar, similar to nested classes in Java.

Layout and drawable resources shouldn't be exposed as public APIs. If they must be exposed, however, then public layouts and drawables must be named using the under_score naming convention, for example layout/simple_list_item_1.xml or drawable/title_bar_tall.xml.

When constants could change, make them dynamic

The compiler might inline constant values, so keeping values the same is considered part of the API contract. If the value of a MIN_FOO or MAX_FOO constant could change in the future, consider making them dynamic methods instead.

CameraManager.MAX_CAMERAS

CameraManager.getMaxCameras()

Consider forward compatibility for callbacks

Constants defined in future API versions aren't known to apps that target older APIs. For this reason, constants delivered to apps should take into consideration that app's target API version and map newer constants to a consistent value. Consider the following scenario:

Hypothetical SDK source:

// 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;

Hypothetical app with targetSdkVersion="22":

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

In this case, the app was designed within the constraints of API level 22 and made a (somewhat) reasonable assumption that there were only two possible states. If the app receives the newly added STATUS_FAILURE_RETRY, however, it interprets this as success.

Methods that return constants can safely handle cases like this by constraining their output to match the API level targeted by the 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;
}

Developers can't anticipate whether a list of constants might change in the future. If you define an API with an UNKNOWN or UNSPECIFIED constant that looks like a catch-all, developers assume that the published constants when they wrote their app are exhaustive. If you're unwilling to set this expectation, reconsider whether a catch-all constant is a good idea for your API.

Additionally, libraries can't specify their own targetSdkVersion separate from the app and handling targetSdkVersion behavior changes from library code is complicated and error prone.

Integer or string constant

Use integer constants and @IntDef if the namespace for values isn't extensible outside of your package. Use string constants if the namespace is shared or can be extended by code outside of your package.

Data classes

Data classes represent a set of immutable properties and provide a small and well-defined set of utility functions for interacting with that data.

Don't use data class in public Kotlin APIs, as the Kotlin compiler doesn't guarantee language API or binary compatibility for generated code. Instead, manually implement the required functions.

Instantiation

In Java, data classes should provide a constructor when there are few properties or use the Builder pattern when there are many properties.

In Kotlin, data classes should provide a constructor with default arguments regardless of the number of properties. Data classes defined in Kotlin might also benefit from providing a builder when targeting Java clients.

Modification and copying

In cases where data needs to be modified, provide either a Builder class with a copy constructor (Java) or a copy() member function (Kotlin) that returns a new object.

When providing a copy() function in Kotlin, arguments must match the class's constructor and defaults must be populated using the object's current values:

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
    )
}

Additional behaviors

Data classes should implement both equals() and hashCode(), and every property must be accounted for in the implementations of these methods.

Data classes can implement toString() with a recommended format matching Kotlin's data class implementation, for example User(var1=Alex, var2=42).

Methods

These are rules about various specifics in methods, around parameters, method names, return types, and access specifiers.

Time

These rules cover how time concepts like dates and duration should be expressed in APIs.

Prefer java.time.* types where possible

java.time.Duration, java.time.Instant and many other java.time.* types are available on all platform versions through desugaring and should be preferred when expressing time in API parameters or return values.

Prefer exposing only variants of an API that accept or return java.time.Duration or java.time.Instant and omit primitive variants with the same use case unless the API domain is one where object allocation in intended usage patterns would have a prohibitive performance impact.

Methods expressing durations should be named duration

If a time value expresses the duration of time involved, name the parameter "duration", not "time".

ValueAnimator.setTime(java.time.Duration);

ValueAnimator.setDuration(java.time.Duration);

Exceptions:

"timeout" is appropriate when the duration specifically applies to a timeout value.

"time" with a type of java.time.Instant is appropriate when referring to a specific point in time, not a duration.

Methods expressing durations or time as a primitive should be named with their time unit, and use long

Methods accepting or returning durations as a primitive should suffix the method name with the associated time units (such as Millis, Nanos, Seconds) to reserve the undecorated name for use with java.time.Duration. See Time.

Methods should also be annotated appropriately with their unit and time base:

• @CurrentTimeMillisLong: Value is a nonnegative timestamp measured as the number of milliseconds since 1970-01-01T00:00:00Z.
• @CurrentTimeSecondsLong: Value is a nonnegative timestamp measured as the number of seconds since 1970-01-01T00:00:00Z.
• @DurationMillisLong: Value is a nonnegative duration in milliseconds.
• @ElapsedRealtimeLong: Value is a nonnegative timestamp in the SystemClock.elapsedRealtime() time base.
• @UptimeMillisLong: Value is a nonnegative timestamp in theSystemClock.uptimeMillis() time base.

Primitive time parameters or return values should use long, not int.

ValueAnimator.setDuration(@DurationMillisLong long);

ValueAnimator.setDurationNanos(long);

Methods expressing units of time should prefer nonabbreviated shorthand for unit names

public void setIntervalNs(long intervalNs);

public void setTimeoutUs(long timeoutUs);

public void setIntervalNanos(long intervalNanos);

public void setTimeoutMicros(long timeoutMicros);

Annotate long time arguments

The platform includes several annotations to provide stronger typing for long-type time units:

• @CurrentTimeMillisLong: Value is a nonnegative timestamp measured as the number of milliseconds since 1970-01-01T00:00:00Z, thus in the System.currentTimeMillis() time base.
• @CurrentTimeSecondsLong: Value is a nonnegative timestamp measured as the number of seconds since 1970-01-01T00:00:00Z.
• @DurationMillisLong: Value is a nonnegative duration in milliseconds.
• @ElapsedRealtimeLong: Value is a nonnegative timestamp in the SystemClock#elapsedRealtime() time base.
• @UptimeMillisLong: Value is a nonnegative timestamp in the SystemClock#uptimeMillis() time base.

Units of measurement

For all methods expressing a unit of measurement other than time, prefer CamelCased SI unit prefixes.

public  long[] getFrequenciesKhz();

public  float getStreamVolumeDb();

Put optional parameters at end of overloads

If you have overloads of a method with optional parameters, keep those parameters at the end and keep consistent ordering with the other parameters:

public int doFoo(boolean flag);

public int doFoo(int id, boolean flag);

public int doFoo(boolean flag);

public int doFoo(boolean flag, int id);

When adding overloads for optional arguments, the behavior of the simpler methods should behave in exactly the same way as if default arguments had been provided to the more elaborate methods.

Corollary: Don't overload methods other than to add optional arguments or to accept different types of arguments if the method is polymorphic. If the overloaded method does something fundamentally different, then give it a new name.

Methods with default parameters must be annotated with @JvmOverloads (Kotlin only)

Methods and constructors with default parameters must be annotated with @JvmOverloads to maintain binary compatibility.

See Function overloads for defaults in the official Kotlin-Java interop guide for more details.

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

Don't remove default parameter values (Kotlin only)

If a method has shipped with a parameter with a default value, removal of the default value is a source-breaking change.

The most distinctive and identifying method parameters should be first

If you have a method with multiple parameters, put the most relevant ones first. Parameters that specify flags and other options are less important than those that describe the object that is being acted upon. If there is a completion callback, put it last.

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);

See also: Put optional parameters at end in overloads

Builders

The Builder pattern is recommended for creating complex Java objects, and is commonly used in Android for cases where:

• The resulting object's properties should be immutable
• There are a large number of required properties, for example many constructor arguments
• There is a complex relationship between properties at construction time, for example a verification step is required. Note that this level of complexity often indicates problems with the API's usability.

Consider whether you need a builder. Builders are useful in an API surface if they are used to:

• Configure only a few of a potentially large set of optional creation parameters
• Configure many different optional or required creation parameters, sometimes of similar or matching types, where call sites could otherwise become confusing to read or error-prone to write
• Configure the creation of an object incrementally, where several different pieces of configuration code might each make calls on the builder as implementation details
• Allow a type to grow by adding additional optional creation parameters in future API versions

If you have a type with three or fewer required parameters and no optional parameters you can almost always skip a builder and use a plain constructor.

Kotlin-sourced classes should prefer @JvmOverloads-annotated constructors with default arguments over Builders, but may choose to improve usability for Java clients by also providing Builders in the cases outlined earlier.

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

Builder classes must return the builder

Builder classes must enable method chaining by returning the Builder object (such as this) from every method except build(). Additional built objects should be passed as arguments -- don't return a different object's builder. For example:

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();
  }
}

In rare cases where a base builder class must support extension, use a generic return type:

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);
}

Builder classes must be created through a constructor

To maintain consistent builder creation through Android API surface, all the builders must be created through a constructor and not a static creator method. For Kotlin-based APIs, the Builder must be public even if Kotlin users are expected to implicitly rely on the builder through a factory method/DSL style creation mechanism. Libraries must not use @PublishedApi internal to selectively hide the Builder class constructor from Kotlin clients.

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

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

All arguments to builder constructors must be required (such as @NonNull)

Optional, for example @Nullable, arguments should be moved to setter methods. The builder constructor should throw an NullPointerException (consider using Objects.requireNonNull) if any required arguments aren't specified.

Builder classes should be final static inner classes of their built types

For the sake of logical organization within a package, builder classes should typically be exposed as final inner classes of their built types, for example Tone.Builder rather than ToneBuilder.

Builders may include a constructor to create a new instance from an existing instance

Builders may include a copy constructor to create a new builder instance from an existing builder or built object. They shouldn't provide alternative methods for creating builder instances from existing builders or build objects.

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);
  }
}

Builder setters should take @Nullable arguments if the builder has copy constructor

Resetting is essential if a new instance of a builder may be created from an existing instance. If no copy constructor is available, then the builder may have either @Nullable or @NonNullable arguments.

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

Builder setters may take @Nullable arguments for optional properties

It's often simpler to use a nullable value for second-degree input, especially in Kotlin, which utilizes default arguments instead of builders and overloads.

Additionally, @Nullable setters will match them with their getters, which must be @Nullable for optional properties.

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();
}

Common usage 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()

The default value (if the setter isn't called), and the meaning of null, must be properly documented in both the setter and the getter.

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

Builder setters can be provided for mutable properties where setters are available on the built class

If your class has mutable properties and needs a Builder class, first ask yourself whether your class should actually have mutable properties.

Next, if you're certain that you need mutable properties, decide which of the following scenarios works better for your expected use case:

1. The built object should be immediately usable, thus setters should be provided for all relevant properties whether mutable or immutable.

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

2. Some additional calls may need to be made before the built object can be useful, thus setters shouldn't be provided for mutable properties.

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

Don't mix the two scenarios.

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

Builders shouldn't have getters

Getter should be on the built object, not the builder.

Builder setters must have corresponding getters on the built class

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();
}

Builder method naming

Builder methods names should use setFoo(), addFoo() or clearFoo() style.

Builder classes are expected to declare a build() method

Builder classes should declare a build() method that returns an instance of the constructed object.

Builder build() methods must return @NonNull objects

A builder's build() method is expected to return a nonnull instance of the constructed object. In the event that the object can't be created due to invalid parameters, validation can be deferred to the build method and an IllegalStateException should be thrown.

Don't expose internal locks

Methods in the public API shouldn't use the synchronized keyword. This keyword causes your object or class to be used as the lock, and because it's exposed to others, you may encounter unexpected side effects if other code outside your class starts using it for locking purposes.

Instead, perform any required locking against an internal, private object.

public synchronized void doThing() { ... }

private final Object mThingLock = new Object();

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

Accessor-styled methods should follow Kotlin property guidelines

When viewed from Kotlin sources, accessor-styled methods -- those using the get, set, or is prefixes -- will also be available as Kotlin properties. For example, int getField() defined in Java is available in Kotlin as the property val field: Int.

For this reason, and to generally meet developer expectations around accessor method behavior, methods using accessor method prefixes should behave similarly to Java fields. Avoid using accessor-style prefixes when:

• The method has side effects -- prefer a more descriptive method name
• The method involves computationally expensive work -- prefer compute
• The method involves blocking or otherwise long-running work to return a value, such as IPC or other I/O -- prefer fetch
• The method blocks the thread until it can return a value -- prefer await
• The method returns a new object instance on every call -- prefer create
• The method may not successfully return a value -- prefer request

Note that performing computationally expensive work once and caching the value for subsequent calls still counts as performing computationally expensive work. Jank isn't amortized across frames.

Use is prefix for boolean accessor methods

This is the standard naming convention for boolean methods and fields in Java. Generally, boolean method and variable names should be written as questions that are answered by the return value.

Java boolean accessor methods should follow a set/is naming scheme and fields should prefer is, as in:

// 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;

Using set/is for Java accessor methods or is for Java fields will allow them to be used as properties from Kotlin:

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

Properties and accessor methods should generally use positive naming, for example Enabled rather than Disabled. Using negative terminology inverts the meaning of true and false and makes it more difficult to reason about behavior.

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

In cases where the boolean describes inclusion or ownership of a property, you may use has rather than is; however, this will not work with Kotlin property syntax:

// 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();

Some alternative prefixes that may be more suitable include can and 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();

Methods that toggle behaviors or features may use the is prefix and Enabled suffix:

// "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()

Similarly, methods that indicate the dependency on other behaviors or features may use is prefix and Supported or Required suffix:

// "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()

Generally, method names should be written as questions that are answered by the return value.

Kotlin property methods

For a class property var foo: Foo Kotlin will generate get/set methods using a consistent rule: prepend get and uppercase the first character for the getter, and prepend set and uppercase the first character for the setter. The property declaration will produce methods named public Foo getFoo() and public void setFoo(Foo foo), respectively.

If the property is of type Boolean an additional rule applies in name generation: if the property name begins with is, then get isn't prepended for the getter method name, the property name itself is used as the getter. Therefore, prefer naming Boolean properties with an is prefix in order to follow the naming guideline:

var isVisible: Boolean

If your property is one of the aforementioned exceptions and begins with an appropriate prefix, use the @get:JvmName annotation on the property to manually specify the appropriate name:

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

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

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

Bitmask accessors

See Use @IntDef for bitmask flags for API guidelines regarding defining bitmask flags.

Setters

Two setter methods should be provided: one that takes a full bitstring and overwrites all existing flags and another that takes a custom bitmask to allow more flexibility.

/**
 * 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

One getter should be provided to obtain the full bitmask.

/**
 * 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();

Use public instead of protected

Always prefer public to protected in public API. Protected access ends up being painful in the long run, because implementers have to override to provide public accessors in cases where external access by default would have been just as good.

Remember that protected visibility doesn't prevent developers from calling an API -- it only makes it slightly more obnoxious.

Implement neither or both of equals() and hashCode()

If you override one, you must override the other.

Implement toString() for data classes

Data classes are encouraged to override toString(), to help developers debug their code.

Document whether the output is for program behavior or debugging

Decide whether you want program behavior to rely on your implementation or not. For example, UUID.toString() and File.toString() document their specific format for programs to use. If you are exposing information for debugging only, like Intent, then imply inherit docs from the superclass.

Don't include extra information

All the information available from toString() should also be available through the public API of the object. Otherwise, you are encouraging developers to parse and rely on your toString() output, which will prevent future changes. A good practice is to implement toString() using only the object's public API.

Discourage reliance on debug output

While it's impossible to prevent developers from depending on debug output, including the System.identityHashCode of your object in its toString() output will make it very unlikely that two different objects will have equal toString() output.

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

This can effectively discourage developers from writing test assertions like assertThat(a.toString()).isEqualTo(b.toString()) on your objects.

Use createFoo when returning newly created objects

Use the prefix create, not get or new, for methods that will create return values, for example by constructing new objects.

When the method will create an object to return, make that clear in the method name.

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

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

Methods accepting File objects should also accept streams

Data storage locations on Android aren't always files on disk. For example, content passed across user boundaries is represented as content:// Uris. To enable processing of various data sources, APIs which accept File objects should also accept InputStream, OutputStream, or both.

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

Take and return raw primitives instead of boxed versions

If you need to communicate missing or null values, consider using -1, Integer.MAX_VALUE, or Integer.MIN_VALUE.

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

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

Avoiding class equivalents of primitive types avoids the memory overhead of these classes, method access to values, and, more importantly, autoboxing that comes from casting between primitive and object types. Avoiding these behaviors saves on memory and on temporary allocations that can lead to expensive and more frequent garbage collections.

Use annotations to clarify valid parameter and return values

Developer annotations were added to help clarify allowable values in various situations. This makes it easier for tools to help developers when they supply incorrect values (for example, passing an arbitrary int when the framework requires one of a specific set of constant values). Use any and all of the following annotations when appropriate:

Nullability

Explicit nullability annotations are required for Java APIs, but the concept of nullability is part of the Kotlin language and nullability annotations should never be used in Kotlin APIs.

@Nullable: Indicates that a given return value, parameter, or field can be null:

@Nullable
public String getName()

public void setName(@Nullable String name)

@NonNull: Indicates that a given return value, parameter, or field can't be null. Marking things as @Nullable is relatively new to Android, so most of Android's API methods aren't consistently documented. Therefore we have a tri-state of "unknown, @Nullable, @NonNull" which is why @NonNull is part of the API guidelines:

@NonNull
public String getName()

public void setName(@NonNull String name)

For Android platform docs, annotating your method parameters will automatically generate documentation in the form "This value may be null." unless "null" is explicitly used elsewhere in the parameter doc.

Existing "not really nullable" methods: Existing methods in the API without a declared @Nullable annotation may be annotated @Nullable if the method can return null under specific, obvious circumstances (such as findViewById()). Companion @NotNull requireFoo() methods that throw IllegalArgumentException should be added for developers who don't want to null check.

Interface methods: new APIs should add the proper annotation when implementing interface methods, like Parcelable.writeToParcel() (i.e, that method in the implementing class should be writeToParcel(@NonNull Parcel, int), not writeToParcel(Parcel, int)); existing APIs that are lacking the annotations don't need to be "fixed", though.

Nullability enforcement

In Java, methods are recommended to perform input validation for @NonNull parameters using Objects.requireNonNull() and throw a NullPointerException when the parameters are null. This is automatically performed in Kotlin.

Resources

Resource identifiers: Integer parameters that denote ids for specific resources should be annotated with the appropriate resource-type definition. There is an annotation for every type of resource, such as @StringRes, @ColorRes, and @AnimRes, in addition to the catch-all @AnyRes. For example:

public void setTitle(@StringRes int resId)

@IntDef for constant sets

Magic constants: String and int parameters that are meant to receive one of a finite set of possible values denoted by public constants should be annotated appropriately with @StringDef or @IntDef. These annotations allow you to create a new annotation that you can use that works like a typedef for allowable parameters. For example:

/** @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);

Methods are recommended to check the validity of the annotated parameters and throw an IllegalArgumentException if the parameter isn't part of the @IntDef

@IntDef for bitmask flags

The annotation can also specify that the constants are flags, and can be combined with & and 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 for string constant sets

There is also the @StringDef annotation, which is exactly like @IntDef in the previous section, but for String constants. You can include multiple "prefix" values which are used to automatically emit documentation for all values.

@SdkConstant for SDK constants

@SdkConstant Annotate public fields when they are one of these SdkConstant values: 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";

Provide compatible nullability for overrides

For API compatibility, the nullability of overrides should be compatible with the current nullability of the parent. The following table represents the compatibility expectations. Plainly, overrides should only be as restrictive or more restrictive than the element they override.

Prefer non-nullable (such as @NonNull) arguments where possible

When methods are overloaded, prefer that all arguments are nonnull.

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

This rule applies to overloaded property setters as well. The primary argument should be nonnull and clearing the property should be implemented as a separate method. This prevents "nonsense" calls where the developer must set trailing parameters even though they aren't required.

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()

Prefer non-nullable (such as @NonNull) return types for containers

For container types such as Bundle or Collection, return an empty -- and immutable, where applicable -- container. In cases where null would be used to distinguish availability of a container, consider providing a separate boolean method.

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

Nullability annotations for get and set pairs must agree

Get and set method pairs for a single logical property should always agree in their nullability annotations. Failing to follow this guideline will defeat Kotlin's property syntax, and adding disagreeing nullability annotations to existing property methods is therefore a source-breaking change for Kotlin users.

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

Return value in failure or error conditions

All APIs should permit apps to react to errors. Returning false, -1, null, or other catch-all values of "something went wrong" don't tell a developer enough about the failure to set user expectations or accurately track reliability of their app in the field. When designing an API, imagine that you are building an app. If you encounter an error, does the API give you enough information to present it to the user or react appropriately?

1. It's fine (and encouraged) to include detailed information in an exception message, but developers shouldn't have to parse it to handle the error appropriately. Verbose error codes or other information should be exposed as methods.
2. Make sure your chosen error handling option gives you the flexibility to introduce new error types in the future. For @IntDef, that means including an OTHER or UNKNOWN value - when returning a new code, you can check the caller's targetSdkVersion to avoid returning an error code the app doesn't know about. For exceptions, have a common superclass that your exceptions implement, so that any code that handles that type will also catch and handle subtypes.
3. It should be difficult or impossible for a developer to accidentally ignore an error -- if your error is communicated by returning a value, annotate your method with @CheckResult.

Prefer throwing a ? extends RuntimeException when a failure or error condition is reached due to something that the developer did wrong, for example ignoring constraints on input parameters or failing to check observable state.

Setter or action (for example, perform) methods may return an integer status code if the action may fail as a result of asynchronously-updated state or conditions outside the developer's control.

Status codes should be defined on the containing class as public static final fields, prefixed with ERROR_, and enumerated in an @hide @IntDef annotation.

Method names should always begin with the verb, not the subject

The name of the method should always begin with the verb (such as get, create, reload, etc.), not the object you're acting on.

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

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

Prefer Collection types over arrays as return or parameter type

Generically typed collection interfaces provide several advantages over arrays, including stronger API contracts around uniqueness and ordering, support for generics, and a number of developer-friendly convenience methods.

Exception for primitives

If the elements are primitives, do prefer arrays instead, in order to avoid the cost of auto-boxing. See Take and return raw primitives instead of boxed versions

Exception for performance-sensitive code

In certain scenarios, where the API is used in performance-sensitive code (like graphics or other measure/layout/draw APIs), it is acceptable to use arrays instead of collections in order to reduce allocations and memory churn.

Exception for Kotlin

Kotlin arrays are invariant and the Kotlin language provides ample utility APIs around arrays, so arrays are on-par with List and Collection for Kotlin APIs intended to be accessed from Kotlin.

Prefer @NonNull collections

Always prefer @NonNull for collection objects. When returning an empty collection, use the appropriate Collections.empty method to return a low cost, correctly typed, and immutable collection object.

Where type annotations are supported, always prefer @NonNull for collection elements.

You should also prefer @NonNull when using arrays instead of collections (see previous item). If object allocation is a concern, create a constant and pass it along - after all, an empty array is immutable. Example:

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;
}

Collection mutability

Kotlin APIs should prefer read-only (not Mutable) return types for collections by default unless the API contract specifically requires a mutable return type.

Java APIs, however, should prefer mutable return types by default because the Android platform implementation of Java APIs doesn't yet provide a convenient implementation of immutable collections. The exception to this rule is Collections.empty return types, which are immutable. In cases where mutability could be exploited by clients -- on purpose or by mistake -- to break the API's intended usage pattern, Java APIs should strongly consider returning a shallow copy of the collection.

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

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

Explicitly mutable return types

APIs that return collections should ideally not modify the returned collection object after returning. If the returned collection must change or be reused in some way -- for example, an adapted view of a mutable dataset -- the precise behavior of when the contents can change must be explicitly documented or follow established API naming conventions.

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

The Kotlin .asFoo() convention is described below and permits the collection returned by .asList() to change if the original collection changes.

Mutability of returned data-type objects

Similar to APIs that return collections, APIs that return data-type objects should ideally not modify the properties of the returned object after returning.

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 extremely limited cases, some performance-sensitive code may benefit from object pooling or reuse. Don't write your own object pool data structure and don't expose reused objects in public APIs. In either case, be extremely careful about managing concurrent access.

Use of vararg parameter type

Both Kotlin and Java APIs are encouraged to use vararg in cases where the developer would be likely to create an array at the call site for the sole purpose of passing multiple, related parameters of the same type.

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);

Defensive copies

Both Java and Kotlin implementations of vararg parameters compile to the same array-backed bytecode and as a result may be called from Java code with a mutable array. API designers are strongly encouraged to create a defensive shallow copy of the array parameter in cases where it will be persisted to a field or anonymous inner class.

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

Note that creating a defensive copy doesn't provide any protection against concurrent modification between the initial method call and the creation of the copy, nor does it protect against mutation of the objects contained in the array.

Provide correct semantics with collection type parameters or returned types

List<Foo> is default option, but consider other types to provide additional meaning:

• Use Set<Foo>, if your API is indifferent to the order of elements and it doesn't allow duplicates or duplicates are meaningless.

• Collection<Foo>, if your API is indifferent to the order and allows duplicates.

Kotlin conversion functions

Kotlin frequently uses .toFoo() and .asFoo() to obtain an object of a different type from an existing object where Foo is the name of the conversion's return type. This is consistent with the familiar JDK Object.toString(). Kotlin takes this further by using it for primitive conversions such as 25.toFloat().

The distinction between conversions named .toFoo() and .asFoo() is significant:

Use .toFoo() when creating a new, independent object

Like .toString(), a "to" conversion returns a new, independent object. If the original object is modified later, the new object won't reflect those changes. Similarly, if the new object is modified later, the old object won't reflect those changes.

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

Use .asFoo() when creating a dependent wrapper, decorated object, or cast

Casting in Kotlin is performed using the as keyword. It reflects a change in interface but not a change in identity. When used as a prefix in an extension function, .asFoo() decorates the receiver. A mutation in the original receiver object will be reflected in the object returned by asFoo(). A mutation in the new Foo object may be reflected in the original object.

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

Conversion functions should be written as extension functions

Writing conversion functions outside of both the receiver and the result class definitions reduces coupling between types. An ideal conversion needs only public API access to the original object. This proves by example that a developer can write analogous conversions to their own preferred types as well.

Throw appropriate specific exceptions

Methods must not throw generic exceptions such as java.lang.Exception or java.lang.Throwable, instead an appropriate specific exception has to be used like java.lang.NullPointerException to allow developers to handle exceptions without being overly broad.

Errors that are unrelated to the arguments provided directly to the publicly invoked method should throw java.lang.IllegalStateException instead of java.lang.IllegalArgumentException or java.lang.NullPointerException.

Listeners and callbacks

These are the rules around the classes and methods used for listener and callback mechanisms.

Callback class names should be singular

Use MyObjectCallback instead of MyObjectCallbacks.

Callback method names should be of the format on

onFooEvent signifies that FooEvent is happening and that the callback should act in response.

Past versus present tense should describe timing behavior

Callback methods regarding events should be named to indicate whether the event has already happened or is in the process of happening.

For example, if the method is called after a click action has been performed:

public void onClicked()

However, if the method is responsible for performing the click action:

public boolean onClick()

Callback registration

When a listener or callback can be added or removed from an object, the associated methods should be named add and remove or register and unregister. Be consistent with the existing convention used by the class or by other classes in the same package. When no such precedent exists, prefer add and remove.

Methods involving registering or unregistering callbacks should specify the whole name of the callback type.

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

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

Avoid getters for callbacks

Don't add getFooCallback() methods. This is a tempting escape hatch for cases where developers may want to chain an existing callback together with their own replacement, but it is brittle and makes the current state difficult to reason about for component developers. For example,

• Developer A calls setFooCallback(a)
• Developer B calls setFooCallback(new B(getFooCallback()))
• Developer A wishes to remove its callback a and has no way to do so without knowledge of B's type, and B having been built to allow such modifications of its wrapped callback.

Accept Executor to control callback dispatch

When registering callbacks that have no explicit threading expectations (pretty much anywhere outside the UI toolkit), it is strongly encouraged to include an Executor parameter as part of registration to allow the developer to specify the thread upon which the callbacks will be invoked.

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

As an exception to our usual guidelines about optional parameters, it is acceptable to provide an overload omitting the Executor even though it isn't the final argument in the parameter list. If the Executor isn't provided, the callback should be invoked on the main thread using Looper.getMainLooper() and this should be documented on the associated overloaded method.

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

Executor implementation gotchas: Note that the following is a valid executor!

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

This means that when implementing APIs that take this form, your incoming binder object implementation on the app process side must call Binder.clearCallingIdentity() before invoking the app's callback on the app-supplied Executor. This way any app code that uses binder identity (such as Binder.getCallingUid()) for permission checks correctly attributes the code running to the app and not to the system process calling into the app. If users of your API want the UID or PID information of the caller then this should be an explicit part of your API surface, rather than implicit based on where the Executor they supplied ran.

Specifying an Executor should be supported by your API. In performance-critical cases apps may need to run code either immediately or synchronously with feedback from your API. Accepting an Executor permits this. Defensively creating an additional HandlerThread or similar to trampoline from defeats this desirable use case.

If an app is going to run expensive code somewhere in their own process, let them. The workarounds that app developers will find to overcome your restrictions will be much harder to support in the long term.

Exception for single callback: when the nature of the events being reported calls for only supporting a single callback instance, use the following style:

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

public void clearFooCallback()

Use Executor instead of Handler

Android's Handler was used as a standard for redirecting callback execution to a specific Looper thread in the past. This standard was changed to prefer Executor as most app developers manage their own thread pools, making the main or UI thread the only Looper thread available to the app. Use Executor to give developers the control they need to reuse their existing/preferred execution contexts.

Modern concurrency libraries like kotlinx.coroutines or RxJava provide their own scheduling mechanisms that perform their own dispatch when needed, which makes it important to provide the ability to use a direct executor (such as Runnable::run) to avoid latency from double thread hops. For example, one hop to post to a Looper thread using a Handler followed by another hop from the app's concurrency framework.

Exceptions to this guideline are rare. Common appeals for an exception include:

I have to use a Looper because I need a Looper to epoll for the event. This exception request is granted as the benefits of Executor can't be realized in this situation.

I don't want app code to block my thread publishing the event. This exception request is typically not granted for code that runs in an app process. Apps that get this wrong are only hurting themselves, not impacting overall system health. Apps that get it right or use a common concurrency framework shouldn't pay additional latency penalties.

Handler is locally consistent with other similar APIs in the same class. This exception request is granted situationally. Preference is for Executor-based overloads to be added, migrating Handler implementations to use the new Executor implementation. (myHandler::post is a valid Executor!) Depending on the size of the class, number of existing Handler methods, and likelihood that developers would need to use existing Handler based methods alongside the new method, an exception may be granted to add a new Handler-based method.

Symmetry in registration

If there is a way to add or register something, there should also be a way to remove/unregister it. The method

registerThing(Thing)

should have a matching

unregisterThing(Thing)

Provide a request identifier

If it is reasonable for a developer to reuse a callback, provide an identifier object to tie the callback to the request.

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

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

Multiple-method callback objects

Multiple-method callbacks should prefer interface and use default methods when adding to previously-released interfaces. Previously, this guideline recommended abstract class due to the lack of default methods in Java 7.

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

Use android.os.OutcomeReceiver when modeling a nonblocking function call

OutcomeReceiver<R,E> reports a result value R when successful or E : Throwable otherwise - the same things a plain method call can do. Use OutcomeReceiver as the callback type when converting a blocking method that returns a result or throws an exception to a nonblocking async method:

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

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

Async methods converted in this way always return void. Any result that requestFoo would return is instead reported to requestFooAsync's callback parameter's OutcomeReceiver.onResult by calling it on the provided executor. Any exception that requestFoo would throw is instead reported to the OutcomeReceiver.onError method in the same way.

Using OutcomeReceiver for reporting async method results also affords a Kotlin suspend fun wrapper for async methods using the Continuation.asOutcomeReceiver extension from androidx.core:core-ktx:

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

Extensions like this enable Kotlin clients to call nonblocking async methods with the convenience of a plain function call without blocking the calling thread. These 1-1 extensions for platform APIs may be offered as part of the androidx.core:core-ktx artifact in Jetpack when combined with standard version compatibility checks and considerations. See the documentation for asOutcomeReceiver for more information, cancellation considerations and samples.

Async methods that don't match the semantics of a method returning a result or throwing an exception when its work is complete shouldn't use OutcomeReceiver as a callback type. Instead consider one of the other options listed in the following section.

Prefer functional interfaces over creating new single abstract method (SAM) types

API level 24 added the java.util.function.* (reference docs) types, which offer generic SAM interfaces such as Consumer<T> that are suitable for use as callback lambdas. In many cases, creating new SAM interfaces provides little value in terms of type safety or communicating intent while unnecessarily expanding the Android API surface area.

Consider using these generic interfaces, rather than creating new ones:

• Runnable: () -> Unit
• Supplier<R>: () -> R
• Consumer<T>: (T) -> Unit
• Function<T,R>: (T) -> R
• Predicate<T>: (T) -> Boolean
• many more available in reference docs

Placement of SAM parameters

SAM parameters should be placed last to enable idiomatic usage from Kotlin, even if the method is being overloaded with additional parameters.

public void schedule(Runnable runnable)

public void schedule(int delay, Runnable runnable)

Docs

These are rules about the public docs (Javadoc) for APIs.

All public APIs must be documented

All public APIs must have sufficient documentation to explain how a developer would use the API. Assume the developer found the method using autocomplete or while browsing through API reference docs and has a minimal amount of context from the adjacent API surface (for example, the same class).

Methods

Method parameters and return values must be documented using @param and @return docs annotations, respectively. Format the Javadoc body as though it's preceded by "This method...".

In cases where a method takes no parameters, has no special considerations, and returns what the method name says it does, you can omit the @return and write docs similar to:

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

Always use links in Javadoc

Docs should link to other docs for related constants, methods, and other elements. Use Javadoc tags (for example, @see and {@link foo}), not just plain-text words.

For the following source example:

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

Don't use raw text or code font:

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

Instead, use links:

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

Note that using an IntDef annotation such as @ValueType on a parameter automatically generates documentation specifying the allowed types. See the guidance on annotations for more information on IntDef.

Run update-api or docs target when adding Javadoc

This rule is particularly important when adding @link or @see tags, and make sure the output looks as expected. ERROR output in Javadoc is often due to bad links. Either the update-api or docs Make target performs this check, but the docs target might be quicker if you're only changing Javadoc and don't otherwise need to run the update-api target.

Use {@code foo} to distinguish Java values

Wrap Java values like true, false, and null with {@code...} to distinguish them from documentation text.

When writing documentation in Kotlin sources, you can wrap code with backticks like you would for Markdown.

@param and @return summaries should be a single sentence fragment

Parameter and return value summaries should start with a lowercase character and contain only a single sentence fragment. If you have additional information that extends beyond a single sentence, move it to the method Javadoc body:

/**
 * @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.
 */

Should be changed to:

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

Docs annotations need explanations

Document why annotations @hide and @removed are hidden from the public API. Include instructions for how to replace API elements marked with the @deprecated annotation.

Use @throws to document exceptions

If a method throws a checked exception, for example IOException, document the exception with @throws. For Kotlin-sourced APIs intended for use by Java clients, annotate functions with @Throws.

If a method throws an unchecked exception indicating a preventable error, for example IllegalArgumentException or IllegalStateException, document the exception with an explanation of why the exception is thrown. The thrown exception should also indicate why it was thrown.

Certain cases of unchecked exception are considered implicit and don't need to be documented, such as NullPointerException or IllegalArgumentException where an argument doesn't match an @IntDef or similar annotation that embeds the API contract into the method signature:

/**
 * ...
 * @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.");
  }
  // ...

Or, in Kotlin:

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

If the method invokes asynchronous code that might throw exceptions, consider how the developer finds out about and responds to such exceptions. Typically this involves forwarding the exception to a callback and documenting the exceptions thrown on the method that receives them. Asynchronous exceptions shouldn't be documented with @throws unless they're actually rethrown from the annotated method.

End the first sentence of docs with a period

The Doclava tool parses docs simplistically, ending the synopsis doc (the first sentence, used in the quick description at the top of the class docs) as soon as it sees a period (.) followed by a space. This causes two problems:

• If a short doc doesn't end with a period, and if that member has inherited docs that are picked up by the tool, then the synopsis also picks up those inherited docs. For example, see actionBarTabStyle in the R.attr docs, which has the description of the dimension added into the synopsis.
• Avoid "e.g." in the first sentence for the same reason, because Doclava ends the synopsis docs after "g.". For example, see TEXT_ALIGNMENT_CENTER in View.java. Note that Metalava automatically corrects this error by inserting a nonbreaking space after the period; however, don't make this mistake in the first place.

Format docs to be rendered in HTML

Javadoc is rendered in HTML, so format these docs accordingly:

• Line breaks should use an explicit <p> tag. Don't add a closing </p> tag.

• Don't use ASCII to render lists or tables.

• Lists should use <ul> or <ol> for unordered and ordered, respectively. Each item should begin with an <li> tag, but doesn't need a closing </li> tag. A closing </ul> or </ol> tag is required after the last item.

• Tables should use <table>, <tr> for rows, <th> for headers, and <td> for cells. All table tags require matching closing tags. You can use class="deprecated" on any tag to denote deprecation.

• To create inline code font, use {@code foo}.

• To create code blocks, use <pre>.

• All text inside a <pre> block is parsed by the browser, so be careful with brackets <>. You can escape them with < and > HTML entities.

• Alternatively, you can leave raw brackets <> in your code snippet if you wrap the offending sections in {@code foo}. For example:

  <pre>{@code <manifest>}</pre>
  

Follow the API reference style guide

To provide consistency in the style for class summaries, method descriptions, parameter descriptions, and other items, follow the recommendations in the official Java language guidelines at How to Write Doc Comments for the Javadoc Tool.

Android Framework-specific rules

These rules are about APIs, patterns, and data structures that are specific to APIs and behaviors built into the Android framework (for example, Bundle or Parcelable).

Intent builders should use the create*Intent() pattern

Creators for intents should use methods named createFooIntent().

Use Bundle instead of creating new general-purpose data structures

Avoid creating new general-purpose data structures to represent arbitrary key to typed value mappings. Instead, consider using Bundle.

This typically comes up when writing platform APIs that serve as communication channels between nonplatform apps and services, where the platform doesn't read the data sent across the channel and the API contract may be partially defined outside of the platform (for example, in a Jetpack library).

In cases where the platform does read the data, avoid using Bundle and prefer a strongly typed data class.

Parcelable implementations must have public CREATOR field

Parcelable inflation is exposed through CREATOR, not raw constructors. If a class implements Parcelable, then its CREATOR field must also be a public API and the class constructor taking a Parcel argument must be private.

Use CharSequence for UI strings

When a string is presented in a user interface, use CharSequence to allow for Spannable instances.

If it's just a key or some other label or value that isn't visible to users, String is fine.

Avoid using Enums

IntDef must be used over enums in all platform APIs, and should be strongly considered in unbundled, library APIs. Use enums only when you're certain that new values won't be added.

Benefits ofIntDef:

• Enables adding values over time
  • Kotlin when statements can fail at runtime if they become no-longer-exhaustive due to an added enum value in platform.
• No classes or objects used at runtime, only primitives
  • While R8 or minfication can avoid this cost for unbundled library APIs, this optimization can't affect platform API classes.

Benefits of Enum

• Idiomatic language feature of Java, Kotlin
• Enables exhaustive switch, when statement usage
  • Note - values must not change over time, see previous list
• Clearly scoped, and discoverable naming
• Enables compile time verification
  • For example, a when statement in Kotlin that returns a value
• Is a functioning class that can implement interfaces, have static helpers, expose member or extension methods, and expose fields.

Follow Android package layering hierarchy

The android.* package hierarchy has an implicit ordering, where lower-level packages can't depend on higher-level packages.

Avoid referring to Google, other companies, and their products

The Android platform is an open-source project and aims to be vendor neutral. The API should be generic and equally usable by system integrators or apps with the requisite permissions.

Parcelable implementations should be final

Parcelable classes defined by the platform are always loaded from framework.jar, so it is invalid for an app to try overriding a Parcelable implementation.

If the sending app extends a Parcelable, the receiving app won't have the sender's custom implementation to unpack with. Note about backward compatibility: if your class historically wasn't final, but didn't have a publicly available constructor, you still can mark it final.

Methods calling into system process should rethrow RemoteException as RuntimeException

RemoteException is typically thrown by internal AIDL, and indicates that the system process has died, or the app is trying to send too much data. In both cases, public API should rethrow as a RuntimeException to prevent apps from persisting security or policy decisions.

If you know the other side of a Binder call is the system process, this boilerplate code is the best-practice:

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

Throw specific exceptions for API changes

Public API behaviors might change across API levels and cause app crashes (for instance to enforce new security policies).

When the API needs to throw for a request that was previously valid, throw a new specific exception instead of a generic one. For example, ExportedFlagRequired instead of SecurityException (and ExportedFlagRequired can extend SecurityException).

This will help app developers and tools detect API behavior changes.

Implement copy constructor instead of clone

Use of the Java clone() method is strongly discouraged due to the lack of API contracts provided by the Object class and difficulties inherent in extending classes that use clone(). Instead, use a copy constructor that takes an object of the same type.

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

Classes that rely on a Builder for construction should consider adding a Builder copy constructor to allow modifications to the copy.

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

Use ParcelFileDescriptor over FileDescriptor

The java.io.FileDescriptor object has a poor definition of ownership, which can result in obscure use-after-close bugs. Instead, APIs should return or accept ParcelFileDescriptor instances. Legacy code can convert between PFD and FD if needed using dup() or getFileDescriptor().

Avoid using odd-sized numerical values

Avoid using short or byte values directly, because they often limit how you might be able to evolve the API in the future.

Avoid using BitSet

java.util.BitSet is great for implementation but not for public API. It's mutable, requires an allocation for high-frequency method calls, and doesn't provide semantic meaning for what each bit represents.

For high-performance scenarios, use an int or long with @IntDef. For low-performance scenarios, consider a Set<EnumType>. For raw binary data, use byte[].

Prefer android.net.Uri

android.net.Uri is the preferred encapsulation for URIs in Android APIs.

Avoid java.net.URI, because it is overly strict in parsing URIs, and never use java.net.URL, because its definition of equality is severely broken.

Hide annotations marked as @IntDef, @LongDef, or @StringDef

Annotations marked as @IntDef, @LongDef, or @StringDef denote a set of valid constants that can be passed to an API. However, when they are exported as APIs themselves, the compiler inlines the constants and only the (now useless) values remain in the annotation's API stub (for the platform) or JAR (for libraries).

As such, usages of these annotations must be marked with the @hide docs annotation in the platform or @RestrictTo.Scope.LIBRARY) code annotation in libraries. They must be marked @Retention(RetentionPolicy.SOURCE) in both cases to prevent them from appearing in API stubs or JARs.

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

When building the platform SDK and library AARs, a tool extracts the annotations and bundles them separately from the compiled sources. Android Studio reads this bundled format and enforces the type definitions.

Don't add new setting provider keys

Don't expose new keys from Settings.Global, Settings.System, or Settings.Secure.

Instead, add a proper getter and setter Java API in a relevant class, which is typically a "manager" class. Add a listener mechanism or a broadcast to notify clients of changes as needed.

SettingsProvider settings have a number of problems compared to getters/setters:

• No type safety.
• No unified way to provide a default value.
• No proper way to customize permissions.
  • For example, it's not possible to protect your setting with a custom permission.
• No proper way to add custom logic properly.
  • For example, it's not possible to change setting A's value depending on setting B's value.

Example: Settings.Secure.LOCATION_MODE has existed for a long time, but the location team has deprecated it for a proper Java API LocationManager.isLocationEnabled() and the MODE_CHANGED_ACTION broadcast, which gave the team a lot more flexibility, and the semantics of the APIs are a lot clearer now.

Don't extend Activity and AsyncTask

AsyncTask is an implementation detail. Instead, expose a listener or, in androidx, a ListenableFuture API instead.

Activity subclasses are impossible to compose. Extending activity for your feature makes it incompatible with other features that require users to do the same. Instead, rely on composition by using tools such as LifecycleObserver.

Use the Context's getUser()

Classes bound to a Context, such as anything returned from Context.getSystemService() should use the user bound to the Context instead of exposing members that target specific users.

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);
  }
}

Exception: A method may accept a user argument if it accepts values that don't represent a single user, such as UserHandle.ALL.

Use UserHandle instead of plain ints

UserHandle is preferred to provide type safety and avoid conflating user IDs with uids.

Foobar getFoobarForUser(UserHandle user);

Foobar getFoobarForUser(int userId);

Where unavoidable, an int representing a user ID must be annotated with @UserIdInt.

Foobar getFoobarForUser(@UserIdInt int user);

Prefer listeners or callbacks to broadcast intents

Broadcast intents are very powerful, but they've resulted in emergent behaviors that can negatively impact system health, and so new broadcast intents should be added judiciously.

Here are some specific concerns which result in us discouraging the introduction of new broadcast intents:

• When sending broadcasts without the FLAG_RECEIVER_REGISTERED_ONLY flag, they force-start any apps that aren't already running. While this can sometimes be an intended outcome, it can result in stampeding of dozens of apps, negatively impacting system health. We'd recommend using alternative strategies, such as JobScheduler, to better coordinate when various preconditions are met.

• When sending broadcasts, there is little ability to filter or adjust the content delivered to apps. This makes it difficult or impossible to respond to future privacy concerns, or introduce behavior changes based on the target SDK of the receiving app.

• Since broadcast queues are a shared resource, they can become overloaded and may not result in timely delivery of your event. We've observed several broadcast queues in the wild which have an end-to-end latency of 10 minutes or longer.

For these reasons, we encourage new features to consider using listeners or callbacks or other facilities such as JobScheduler instead of broadcast intents.

In cases where broadcast intents still remain the ideal design, here are some best-practices that should be considered:

• If possible, use Intent.FLAG_RECEIVER_REGISTERED_ONLY to limit your broadcast to apps that are already running. For example, ACTION_SCREEN_ON uses this design to avoid waking up apps.
• If possible, use Intent.setPackage() or Intent.setComponent() to target the broadcast at a specific app of interest. For example, ACTION_MEDIA_BUTTON uses this design to focus on the current app handling playback controls.
• If possible, define your broadcast as a <protected-broadcast> to prevent malicious apps from impersonating the OS.

Intents in system-bound developer services

Services that are intended to be extended by the developer and bound by the system, for example abstract services like NotificationListenerService, may respond to an Intent action from the system. Such services should meet the following criteria:

1. Define a SERVICE_INTERFACE string constant on the class containing the fully-qualified class name of the service. This constant must be annotated with @SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION).
2. Document on the class that a developer must add an <intent-filter> to their AndroidManifest.xml in order to receive Intents from the platform.
3. Strongly consider adding a system-level permission to prevent rogue apps from sending Intents to developer services.

Kotlin-Java interop

See the official Android Kotlin-Java interop guide for a full list of guidelines. Select guidelines have been copied to this guide to improve discoverability.

API visibility

Some Kotlin APIs, like suspend funs, aren't intended to be used by Java developers; however, don't attempt to control language-specific visibility using @JvmSynthetic as it has side-effects on how the API is presented in debuggers that make debugging more difficult.

See the Kotlin-Java interop guide or Async guide for specific guidance.

Companion objects

Kotlin uses companion object to expose static members. In some cases, these will show up from Java on an inner class named Companion rather than on the containing class. Companion classes may show as empty classes in API text files -- that is working as intended.

To maximize compatibility with Java, annotate companion objects' non-constant fields with @JvmField and public functions with @JvmStatic to expose them directly on the containing class.

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

Evolution of Android platform APIs

This section describes policies regarding what types of changes you can make to existing Android APIs and how you should implement those changes to maximize compatibility with existing apps and codebases.

Binary-breaking changes

Avoid binary-breaking changes in finalized public API surfaces. These types of changes generally raise errors when running make update-api, but there might be edge cases that Metalava's API check doesn't catch. When in doubt, refer to the Eclipse Foundation's Evolving Java-based APIs guide for a detailed explanation of what types of API changes are compatible in Java. Binary-breaking changes in hidden (for example, system) APIs should follow the deprecate/replace cycle.

Source-breaking changes

We discourage source-breaking changes even if they aren't binary breaking. One example of a binary compatible but source-breaking change is adding a generic to an existing class, which is binary compatible but can introduce compilation errors due to inheritance or ambiguous references. Source-breaking changes won't raise errors when running make update-api, so you must take care to understand the impact of changes to existing API signatures.

In some cases, source-breaking changes become necessary to improve the developer experience or code correctness. For example, adding nullability annotations to Java sources improves interoperability with Kotlin code and reduces the likelihood of errors, but often requires changes -- sometimes significant changes -- to source code.

Changes to private APIs

You can change APIs annotated with @TestApi at any time.

You must preserve APIs annotated with @SystemApi for three years. You must remove or refactor a system API on the following schedule:

• API y - Added
• API y+1 - Deprecation
  • Mark the code with @Deprecated.
  • Add replacements, and link to the replacement in the Javadoc for the deprecated code using the @deprecated docs annotation.
  • During the development cycle, file bugs against internal users telling them the API is being deprecated. This helps validate that the replacement APIs are adequate.
• API y+2 - Soft removal
  • Mark the code with @removed.
  • Optionally, throw or no-op for apps that target the current SDK level for the release.
• API y+3 - Hard removal
  • Completely remove the code from the source tree.

Deprecation

We consider deprecation an API change, and it can occur in a major (such as letter) release. Use the @Deprecated source annotation and @deprecated <summary> docs annotation together when deprecating APIs. Your summary must include a migration strategy. This strategy might link to a replacement API or explain why you shouldn't use the API:

/**
 * 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)

You must also deprecate APIs defined in XML and exposed in Java, including attributes and styleable properties exposed in the android.R class, with a summary:

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

When to deprecate an API

Deprecations are most useful for discouraging adoption of an API in new code.

We also require that you mark APIs as @deprecated before they're @removed, but this doesn't provide strong motivation for developers to migrate away from an API they're already using.

Before deprecating an API, consider the impact on developers. The effects of deprecating an API include:

• javac emits a warning during compilation.
  • Deprecation warnings can't be suppressed globally or baselined, so developers using -Werror need to individually fix or suppress every usage of a deprecated API before they can update their compile SDK version.
  • Deprecation warnings on imports of deprecated classes can't be suppressed. As a result, developers need to inline the fully qualified class name for every usage of a deprecated class before they can update their compile SDK version.
• Documentation on d.android.com shows a deprecation notice.
• IDEs like Android Studio show a warning at the API usage site.
• IDEs might down-rank or hide the API from auto-complete.

As a result, deprecating an API can discourage the developers who are the most concerned about code health (those using -Werror) from adopting new SDKs. Developers who aren't concerned about warnings in their existing code are likely to ignore deprecations altogether.

An SDK that introduces a large number of deprecations makes both of these cases worse.

For this reason, we recommend deprecating APIs only in cases where:

• We plan to @remove the API in a future release.
• API use leads to incorrect or undefined behavior that we can't fix without breaking compatibility.

When you deprecate an API and replace it with a new API, we strongly recommend adding a corresponding compatibility API to a Jetpack library like androidx.core to simplify supporting both old and new devices.

We don't recommend deprecating APIs that work as intended in current and future releases:

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

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

Deprecation is appropriate in cases where APIs can no longer maintain their documented behaviors:

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

Changes to deprecated APIs

You must maintain the behavior of deprecated APIs. This means test implementations must remain the same, and tests must continue to pass after you have deprecated the API. If the API doesn't have tests, you should add tests.

Don't expand deprecated API surfaces in future releases. You can add lint correctness annotations (for example, @Nullable) to an existing deprecated API, but shouldn't add new APIs.

Don't add new APIs as deprecated. If any APIs were added and subsequently deprecated within a prerelease cycle (thus would initially enter the public API surface as deprecated), you must remove them before finalizing the API.

Soft removal

Soft removal is a source-breaking change, and you should avoid it in public APIs unless the API Council explicitly approves it. For system APIs, you must deprecate the API for the duration of a major release before a soft removal. Remove all docs references to the APIs and use the @removed <summary> docs annotation when soft-removing APIs. Your summary must include the reason for removal and can include a migration strategy, as we explained in Deprecation.

The behavior of soft-removed APIs can be maintained as is, but more importantly must be preserved such that existing callers won't crash when calling the API. In some cases, that might mean preserving behavior.

Test coverage must be maintained, but the content of the tests might need to change to accommodate for behavioral changes. Tests must still validate that existing callers don't crash at run time. You can maintain the behavior of soft-removed APIs as is, but more importantly, you must preserve it such that existing callers won't crash when calling the API. In some cases, that might mean preserving behavior.

You must maintain test coverage, but the content of the tests might need to change to accommodate behavioral changes. Tests must still validate that existing callers don't crash at run time.

At a technical level, we remove the API from the SDK stub JAR and compile-time classpath using the @remove Javadoc annotation, but it still exists on the run-time classpath -- similar to @hide APIs:

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

From an app developer perspective, the API no longer appears in auto-complete and source code that references the API won't compile when the compileSdk is equal to or later than the SDK at which the API was removed; however, source code continues to compile successfully against earlier SDKs and binaries that reference the API continue to work.

Certain categories of API must not be soft removed. You must not soft remove certain categories of API.

Abstract methods

You must not soft remove abstract methods on classes that developers might extend. Doing so makes it impossible for developers to successfully extend the class across all SDK levels.

In rare cases where it was never and won't be possible for developers to extend a class, you can still soft remove abstract methods.

Hard removal

Hard removal is a binary-breaking change and should never occur in public APIs.

Discouraged annotation

We use the @Discouraged annotation to indicate that we don't recommend an API in most (>95%) cases. Discouraged APIs differ from deprecated APIs in that there exists a narrow critical use case that prevents deprecation. When you mark an API as discouraged, you must provide an explanation and an alternative solution:

@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);
}

You shouldn't add new APIs as discouraged.

Changes to the behavior of existing APIs

In some cases, you might want to change the implementation behavior of an existing API. For example, in Android 7.0 we improved DropBoxManager to clearly communicate when developers tried posting events that were too large to send across Binder.

However, to avoid causing problems for existing apps, we strongly recommend preserving a safe behavior for older apps. We've historically guarded these behavior changes based on the ApplicationInfo.targetSdkVersion of the app, but we've recently migrated to require using the App Compatibility Framework. Here's an example of how to implement a behavior change using this new framework:

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
    }
  }
}

Using this App Compatibility Framework design enables developers to temporarily disable specific behavior changes during preview and beta releases as part of debugging their apps, instead of forcing them to adjust to dozens of behavior changes simultaneously.

Forward compatibility

Forward compatibility is a design characteristic that allows a system to accept input intended for a later version of itself. In the case of API design, you must pay special attention to the initial design as well as future changes because developers expect to write code once, test it once, and have it run everywhere without issue.

The following cause the most common forward-compatibility issues in Android:

• Adding new constants to a set (such as @IntDef or enum) previously assumed to be complete (for example, where switch has a default that throws an exception).
• Adding support for a feature that isn't captured directly in the API surface (for example, support for assigning ColorStateList-type resources in XML where previously only <color> resources were supported).
• Loosening restrictions on run-time checks, for example removing a requireNotNull() check that was present on lower versions.

In all of these cases, developers find out that something is wrong only at run time. Worse, they might find out as a result of crash reports from older devices in the field.

Additionally, these cases are all technically valid API changes. They don't break binary or source compatibility and API lint won't catch any of these issues.

As a result, API designers must pay careful attention when modifying existing classes. Ask the question, "Is this change going to cause code that's written and tested only against the latest version of the platform to fail on lower versions?"

XML schemas

If an XML schema serves as a stable interface between components, that schema must be explicitly specified and must evolve in a backward-compatible manner, similar to other Android APIs. For example, the structure of XML elements and attributes must be preserved similar to how methods and variables are maintained on other Android API surfaces.

XML deprecation

If you'd like to deprecate an XML element or attribute, you can add the xs:annotation marker, but you must continue to support any existing XML files by following the typical @SystemApi evolution lifecycle.

<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>

Element types must be preserved

Schemas support the sequence element, choice element and all elements as child elements of complexType element. However, these child elements differ in the number and order of their child elements, so modifying an existing type would be an incompatible change.

If you want to modify an existing type, the best-practice is to deprecate the old type and introduce a new type to replace it.

<!-- 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>

Mainline-specific patterns

Mainline is a project to allow updating subsystems ("mainline modules") of the Android OS individually, rather than updating the whole system image.

Mainline modules have to be "unbundled" from the core platform, which means all the interactions between each module and the rest of the world have to be done using formal (public or system) APIs.

There are certain design patterns mainline modules should follow. This section describes them.

The <Module>FrameworkInitializer pattern

If a mainline module needs to exposes @SystemService classes (for example, JobScheduler) then use the following pattern:

• Expose a <YourModule>FrameworkInitializer class from your module. This class needs to be in $BOOTCLASSPATH. Example: StatsFrameworkInitializer

• Mark it with @SystemApi(client = MODULE_LIBRARIES).

• Add a public static void registerServiceWrappers() method to it.

• Use SystemServiceRegistry.registerContextAwareService() to register a service manager class when it needs a reference to a Context.

• Use SystemServiceRegistry.registerStaticService() to register a service manager class when it doesn't need a reference to a Context.

• Call the registerServiceWrappers() method from SystemServiceRegistry's static initializer.

The <Module>ServiceManager pattern

Normally, in order to register system service binder objects or get references to them, one would use ServiceManager, but mainline modules can't use it because it's hidden. This class is hidden because mainline modules aren't supposed to register or refer to system service binder objects exposed by the static platform or by other modules.

Mainline modules can use the following pattern instead to be able to register and get references to binder services that are implemented inside the module.

• Create a <YourModule>ServiceManager class, following the design of TelephonyServiceManager

• Expose the class as @SystemApi. If you only need to access it from $BOOTCLASSPATH classes or system server classes, you can use @SystemApi(client = MODULE_LIBRARIES); otherwise @SystemApi(client = PRIVILEGED_APPS) would work.

• This class would consists of:

  • A hidden constructor, so only the static platform code can instantiate it.
  • Public getter methods that return a ServiceRegisterer instance for a specific name. If you have one binder object, then you need one getter method. If you have two, then you need two getters.
  • In ActivityThread.initializeMainlineModules(), instantiate this class, and pass it to a static method exposed by your module. Normally, you add a static @SystemApi(client = MODULE_LIBRARIES) API in your FrameworkInitializer class that takes it.

This pattern would prevent other mainline modules from accessing these APIs because there's no way for other modules to get an instance of <YourModule>ServiceManager, even though the get() and register() APIs are visible to them.

Here is how telephony gets a reference to the telephony service: code search link.

If your implements a service binder object in native code, you use the AServiceManager native APIs. These APIs correspond to the ServiceManager Java APIs but the native ones are directly exposed to mainline modules. Don't use them to register or refer to binder objects that aren't owned by your module. If you expose a binder object from native, your <YourModule>ServiceManager.ServiceRegisterer doesn't need a register() method.

Permission definitions in Mainline modules

Mainline modules containing APKs may define (custom) permissions in their APK AndroidManifest.xml in the same way as a regular APK.

If the defined permission is only used internally within a module, its permission name should be prefixed with the APK package name, for example:

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

If the defined permission is to be provided as part of an updatable platform API to other apps, its permission name should be prefixed with "android.permission." (like any static platform permission) plus the module package name, to signal it's a platform API from a module while avoiding any naming conflicts, for example:

<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" />

Then the module can expose this permission name as an API constant in its API surface, for example HealthPermissions.READ_ACTIVE_CALORIES_BURNED.