دستورالعمل های Android API، دستورالعمل های Android API

این صفحه در نظر گرفته شده است تا راهنمای توسعه دهندگان باشد تا اصول کلی را که شورای API در بررسی های API اعمال می کند، درک کنند.

علاوه بر پیروی از این دستورالعمل ها هنگام نوشتن API، توسعه دهندگان باید ابزار API Lint را اجرا کنند، که بسیاری از این قوانین را در بررسی هایی که علیه API ها اجرا می شود، رمزگذاری می کند.

این را به عنوان راهنمای قوانینی که توسط آن ابزار Lint رعایت می‌شود، به‌علاوه توصیه‌های کلی در مورد قوانینی که نمی‌توان با دقت بالا در آن ابزار مدون کرد، در نظر بگیرید.

ابزار API Lint

API Lint در ابزار تجزیه و تحلیل استاتیک Metalava یکپارچه شده است و در حین اعتبارسنجی در CI به طور خودکار اجرا می شود. می توانید آن را به صورت دستی از یک پرداخت پلتفرم محلی با استفاده از m checkapi یا یک پرداخت محلی AndroidX با استفاده از ./gradlew :path:to:project:checkApi اجرا کنید.

قوانین API

پلتفرم Android و بسیاری از کتابخانه‌های Jetpack قبل از ایجاد این مجموعه دستورالعمل‌ها وجود داشته‌اند، و سیاست‌هایی که بعداً در این صفحه ارائه می‌شوند به طور مداوم در حال تغییر هستند تا نیازهای اکوسیستم اندروید را برآورده کنند.

در نتیجه، برخی از API های موجود ممکن است از دستورالعمل ها پیروی نکنند. در موارد دیگر، ممکن است تجربه کاربری بهتری را برای توسعه دهندگان برنامه فراهم کند اگر یک API جدید با APIهای موجود سازگار بماند به جای اینکه به طور دقیق از دستورالعمل ها پیروی کند.

اگر سؤالات دشواری در مورد یک API وجود دارد که باید حل شود یا دستورالعمل هایی که باید به روز شوند، از قضاوت خود استفاده کنید و با شورای API تماس بگیرید.

اصول API

این دسته به جنبه های اصلی یک API اندروید مربوط می شود.

همه API ها باید پیاده سازی شوند

صرف نظر از مخاطبان یک API (به عنوان مثال، عمومی یا @SystemApi )، همه سطوح API باید در هنگام ادغام یا نمایش به عنوان API اجرا شوند. موارد خرد API را با پیاده سازی ادغام نکنید تا در تاریخ بعدی ارائه شود.

سطوح API بدون پیاده سازی مشکلات متعددی دارند:

• هیچ تضمینی وجود ندارد که یک سطح مناسب یا کامل در معرض دید قرار گرفته باشد. تا زمانی که یک API توسط کلاینت‌ها آزمایش یا استفاده نشود، هیچ راهی برای تأیید اینکه یک کلاینت دارای APIهای مناسب برای استفاده از این ویژگی است، وجود ندارد.
• API های بدون پیاده سازی را نمی توان در پیش نمایش های برنامه نویس آزمایش کرد.
• API های بدون پیاده سازی را نمی توان در CTS آزمایش کرد.

همه API ها باید تست شوند

این مطابق با الزامات پلتفرم CTS، سیاست های AndroidX و به طور کلی این ایده است که API ها باید پیاده سازی شوند.

آزمایش سطوح API تضمینی پایه برای قابل استفاده بودن سطح API ارائه می دهد و ما موارد استفاده مورد انتظار را بررسی کرده ایم. آزمایش وجود کافی نیست. رفتار خود API باید آزمایش شود.

تغییری که یک API جدید اضافه می‌کند باید شامل تست‌های مربوطه در همان مبحث CL یا Gerrit باشد.

APIها نیز باید قابل آزمایش باشند. شما باید بتوانید به این سوال پاسخ دهید که "یک توسعه دهنده برنامه چگونه کدی را که از API شما استفاده می کند تست می کند؟"

همه APIها باید مستند باشند

مستندسازی بخش کلیدی قابلیت استفاده API است. در حالی که نحو یک سطح API ممکن است واضح به نظر برسد، هر کلاینت جدیدی معنای، رفتار یا زمینه پشت API را درک نخواهد کرد.

همه APIهای تولید شده باید با دستورالعمل ها مطابقت داشته باشند

APIهای تولید شده توسط ابزارها باید از دستورالعمل‌های API مشابه کدهای دست‌نویس پیروی کنند.

ابزارهایی که برای تولید API ها منع می شوند:

• AutoValue : دستورالعمل‌ها را به روش‌های مختلف نقض می‌کند، به عنوان مثال، هیچ راهی برای پیاده‌سازی کلاس‌های ارزش نهایی یا سازنده‌های نهایی با روش کارکرد AutoValue وجود ندارد.

سبک کد

این دسته به سبک کد کلی مربوط می شود که توسعه دهندگان باید از آن استفاده کنند، به خصوص هنگام نوشتن API های عمومی.

به جز موارد ذکر شده، از قراردادهای استاندارد کدگذاری پیروی کنید

قراردادهای کدنویسی اندروید برای مشارکت کنندگان خارجی در اینجا مستند شده است:

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

به طور کلی، ما تمایل داریم از قوانین کدگذاری استاندارد جاوا و کاتلین پیروی کنیم.

حروف اختصاری نباید در نام روش ها با حروف بزرگ نوشته شوند

به عنوان مثال: نام متد باید runCtsTests باشد نه runCTSTests .

نام ها نباید به Impl ختم شوند

این جزئیات پیاده سازی را آشکار می کند، از آن اجتناب کنید.

کلاس ها

این بخش قوانین مربوط به کلاس ها، رابط ها و ارث را توضیح می دهد.

کلاس های عمومی جدید را از کلاس پایه مناسب به ارث ببرید

وراثت عناصر API را در زیر کلاس شما نشان می دهد که ممکن است مناسب نباشند. برای مثال، یک زیر کلاس عمومی جدید از FrameLayout شبیه FrameLayout به علاوه رفتارها و عناصر API جدید است. اگر آن API ارثی شده برای مورد استفاده شما مناسب نیست، از یک کلاس بالاتر از درخت، به عنوان مثال، ViewGroup یا View ، ارث بری کنید.

اگر وسوسه شدید که روش‌های کلاس پایه را برای پرتاب UnsupportedOperationException نادیده بگیرید، در مورد کلاس پایه که استفاده می‌کنید تجدید نظر کنید.

از کلاس های مجموعه پایه استفاده کنید

چه یک مجموعه را به عنوان آرگومان در نظر بگیرید یا آن را به عنوان یک مقدار برگردانید، همیشه کلاس پایه را بر پیاده سازی خاص ترجیح دهید (مانند بازگشت List<Foo> به جای ArrayList<Foo> ).

از یک کلاس پایه استفاده کنید که محدودیت های مناسب برای API را بیان می کند. به عنوان مثال، از List برای یک API که مجموعه آن باید سفارش داده شود، و از Set برای یک API که مجموعه آن باید از عناصر منحصر به فرد تشکیل شده باشد، استفاده کنید.

در کاتلین، مجموعه های تغییرناپذیر را ترجیح دهید. برای جزئیات بیشتر به تغییرپذیری مجموعه مراجعه کنید.

کلاس های انتزاعی در مقابل رابط ها

جاوا 8 از روش‌های رابط پیش‌فرض پشتیبانی می‌کند، که به طراحان API اجازه می‌دهد تا با حفظ سازگاری باینری، متدهایی را به رابط‌ها اضافه کنند. کد پلتفرم و تمام کتابخانه های Jetpack باید جاوا 8 یا جدیدتر را هدف قرار دهند.

در مواردی که اجرای پیش‌فرض بدون حالت است، طراحان API باید اینترفیس‌ها را به کلاس‌های انتزاعی ترجیح دهند - یعنی روش‌های رابط پیش‌فرض را می‌توان به عنوان فراخوانی برای روش‌های رابط دیگر پیاده‌سازی کرد.

در مواردی که توسط اجرای پیش فرض نیاز به سازنده یا حالت داخلی است، باید از کلاس های انتزاعی استفاده شود.

در هر دو مورد، طراحان API می توانند برای ساده کردن استفاده به عنوان لامبدا، یک روش را انتزاعی بگذارند:

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

نام کلاس ها باید منعکس کننده آن چیزی باشد که بسط می دهد

به عنوان مثال، کلاس هایی که Service گسترش می دهند برای وضوح باید FooService نامیده شوند:

public class IntentHelper extends Service {}

public class IntentService extends Service {}

پسوندهای عمومی

از استفاده از پسوندهای نام کلاس عمومی مانند Helper و Util برای مجموعه ای از متدهای کاربردی خودداری کنید. در عوض، متدها را مستقیماً در کلاس‌های مرتبط یا در توابع پسوند Kotlin قرار دهید.

در مواردی که متدها چندین کلاس را به هم متصل می کنند، به کلاس حاوی یک نام معنادار بدهید که توضیح دهد که چه کار می کند.

در موارد بسیار محدود، استفاده از پسوند Helper ممکن است مناسب باشد:

• برای ترکیب رفتار پیش فرض استفاده می شود
• ممکن است شامل تفویض رفتار موجود به کلاس های جدید باشد
• ممکن است نیاز به حالت تداوم داشته باشد
• به طور معمول شامل View است

به عنوان مثال، اگر راهنمایی ابزار backporting مستلزم تداوم وضعیت مرتبط با View و فراخوانی چندین روش در View برای نصب backport باشد، TooltipHelper یک نام کلاس قابل قبول خواهد بود.

کدهای تولید شده توسط IDL را مستقیماً به عنوان APIهای عمومی در معرض نمایش قرار ندهید

کد تولید شده توسط IDL را به عنوان جزئیات پیاده سازی نگه دارید. این شامل پروتوباف، سوکت ها، FlatBuffers یا هر سطح API غیر جاوا و غیر NDK می شود. با این حال، بیشتر IDL در اندروید در AIDL است، بنابراین این صفحه بر روی AIDL تمرکز دارد.

کلاس های AIDL تولید شده الزامات راهنمای سبک API را برآورده نمی کنند (برای مثال، نمی توانند از بارگذاری اضافه استفاده کنند) و ابزار AIDL به صراحت برای حفظ سازگاری API زبان طراحی نشده است، بنابراین نمی توانید آنها را در یک API عمومی جاسازی کنید.

در عوض، یک لایه API عمومی در بالای رابط AIDL اضافه کنید، حتی اگر در ابتدا یک پوشش کم عمق باشد.

رابط های بایندر

اگر رابط Binder یک جزئیات پیاده‌سازی باشد، می‌توان آن را آزادانه در آینده تغییر داد، با لایه عمومی که اجازه می‌دهد سازگاری مورد نیاز به عقب حفظ شود. برای مثال، ممکن است لازم باشد آرگومان‌های جدیدی را به تماس‌های داخلی اضافه کنید، یا ترافیک IPC را با استفاده از دسته‌بندی یا استریم، استفاده از حافظه مشترک یا موارد مشابه بهینه کنید. اگر رابط AIDL شما API عمومی نیز باشد، هیچ یک از اینها قابل انجام نیست.

برای مثال، FooService به‌عنوان یک API عمومی مستقیماً در معرض نمایش قرار ندهید:

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

در عوض، رابط Binder را در یک مدیر یا کلاس دیگر قرار دهید:

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

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

اگر بعداً یک آرگومان جدید برای این فراخوانی مورد نیاز باشد، رابط داخلی می تواند اضافه بارهای حداقلی و راحت به API عمومی اضافه شود. می‌توانید از لایه بسته‌بندی برای رسیدگی به سایر نگرانی‌های مربوط به سازگاری با عقب با پیشرفت پیاده‌سازی استفاده کنید:

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

برای رابط‌های Binder که بخشی از پلتفرم اندروید نیستند (به عنوان مثال، یک رابط خدماتی که توسط سرویس‌های Google Play برای استفاده برنامه‌ها صادر می‌شود)، نیاز به یک رابط IPC پایدار، منتشر شده و نسخه‌شده به این معنی است که تکامل خود رابط بسیار سخت‌تر است. با این حال، داشتن یک لایه پوششی در اطراف آن، برای مطابقت با سایر دستورالعمل‌های API و آسان‌تر کردن استفاده از همان API عمومی برای نسخه جدید رابط IPC، در صورت لزوم، ارزشمند است.

از اشیاء بایندر خام در API عمومی استفاده نکنید

یک شی Binder به خودی خود معنایی ندارد و بنابراین نباید در API عمومی استفاده شود. یکی از موارد استفاده رایج استفاده از Binder یا IBinder به عنوان نشانه است زیرا دارای معنایی هویت است. به جای استفاده از یک شی Binder خام، از یک کلاس توکن wrapper استفاده کنید.

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

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

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

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

کلاس های مدیر باید نهایی باشد

کلاس های مدیر باید به عنوان final اعلام شود. کلاس های مدیر با سرویس های سیستم صحبت می کنند و تنها نقطه تعامل هستند. نیازی به سفارشی سازی نیست پس آن را final اعلام کنید.

از CompletableFuture یا Future استفاده نکنید

java.util.concurrent.CompletableFuture دارای یک سطح API بزرگ است که امکان جهش دلخواه مقدار آینده را فراهم می کند و دارای پیش فرض های مستعد خطا است.

برعکس، java.util.concurrent.Future از گوش دادن غیرانسدادی استفاده نمی کند و استفاده از آن را با کدهای ناهمزمان سخت می کند.

در کد پلتفرم و APIهای کتابخانه سطح پایین که توسط کاتلین و جاوا مصرف می‌شوند ، ترکیبی از یک فراخوان تکمیل، Executor و اگر API از CancellationSignal لغو پشتیبانی می‌کند، ترجیح می‌دهند.

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

اگر Kotlin را هدف قرار می دهید ، توابع suspend ترجیح دهید.

suspend fun asyncLoadFoo(): Foo

در کتابخانه های یکپارچه سازی خاص جاوا ، می توانید از ListenableFuture Guava استفاده کنید.

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

از اختیاری استفاده نکنید

در حالی که Optional می تواند در برخی از سطوح API مزایایی داشته باشد، با سطح سطح API موجود Android سازگار نیست. @Nullable و @NonNull کمک ابزاری را برای ایمنی null ارائه می‌کنند و Kotlin قراردادهای پوچ‌پذیری را در سطح کامپایلر اجرا می‌کند و Optional را غیرضروری می‌کند.

برای ابتدایی های اختیاری، از متدهای has جفت و get استفاده کنید. اگر مقدار تنظیم نشده باشد ( false has )، متد get باید یک IllegalStateException پرتاب کند.

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

از سازنده های خصوصی برای کلاس های غیرقابل استفاده استفاده کنید

کلاس‌هایی که فقط می‌توانند توسط Builder s ایجاد شوند، کلاس‌هایی که فقط شامل ثابت‌ها یا متدهای استاتیک هستند، یا کلاس‌های غیرقابل مثال باید حداقل شامل یک سازنده خصوصی باشند تا از نمونه‌سازی با استفاده از سازنده پیش‌فرض بدون آرگ جلوگیری شود.

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

تک تن ها

Singleton دلسرد می شود زیرا آنها دارای معایب مربوط به آزمایش زیر هستند:

1. ساخت و ساز توسط کلاس مدیریت می شود و از استفاده تقلبی جلوگیری می کند
2. به دلیل ماهیت ساکن تک قلو، آزمایش ها نمی توانند هرمتیک باشند
3. برای حل این مشکلات، توسعه‌دهندگان یا باید جزئیات داخلی تک‌تنه را بدانند یا یک پوشش در اطراف آن ایجاد کنند

الگوی تک نمونه را ترجیح دهید، که برای رسیدگی به این مسائل به یک کلاس پایه انتزاعی متکی است.

نمونه واحد

کلاس‌های نمونه منفرد از یک کلاس پایه انتزاعی با سازنده private یا internal استفاده می‌کنند و یک متد getInstance() برای به دست آوردن یک نمونه ارائه می‌کنند. متد getInstance() باید همان شی را در فراخوانی های بعدی برگرداند.

شی ای که توسط getInstance() برگردانده می شود باید یک پیاده سازی خصوصی از کلاس پایه انتزاعی باشد.

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 با singleton در این است که توسعه دهندگان می توانند نسخه جعلی SingleInstance را ایجاد کنند و از چارچوب تزریق وابستگی خود برای مدیریت پیاده سازی بدون نیاز به ایجاد wrapper استفاده کنند، یا کتابخانه می تواند تقلبی خود را در یک مصنوع -testing ارائه دهد.

کلاس هایی که منابع را آزاد می کنند باید AutoCloseable را پیاده سازی کنند

کلاس‌هایی که منابع را از طریق close ، release ، destroy یا روش‌های مشابه آزاد می‌کنند باید java.lang.AutoCloseable پیاده‌سازی کنند تا به توسعه‌دهندگان این امکان را بدهد که به طور خودکار این منابع را هنگام استفاده از بلوک try-with-resources پاک کنند.

از معرفی زیر کلاس‌های View جدید در اندروید خودداری کنید.*

کلاس‌های جدیدی را معرفی نکنید که به‌طور مستقیم یا غیرمستقیم از android.view.View در API عمومی پلتفرم (یعنی در android.* ) به ارث می‌برند.

جعبه ابزار UI اندروید اکنون اولین نوشتن است. ویژگی‌های جدید رابط کاربری که توسط این پلتفرم در معرض دید قرار می‌گیرند باید به‌عنوان APIهای سطح پایین‌تر که می‌توانند برای پیاده‌سازی Jetpack Compose و اجزای رابط کاربری اختیاری مبتنی بر View برای توسعه‌دهندگان در کتابخانه‌های Jetpack مورد استفاده قرار گیرند. ارائه این مؤلفه‌ها در کتابخانه‌ها فرصت‌هایی را برای پیاده‌سازی پس‌پورت‌شده زمانی که ویژگی‌های پلتفرم در دسترس نیستند، فراهم می‌کند.

فیلدها

این قوانین در مورد فیلدهای عمومی در کلاس ها هستند.

زمینه های خام را در معرض نمایش قرار ندهید

کلاس های جاوا نباید فیلدها را مستقیماً در معرض دید قرار دهند. فیلدها باید خصوصی باشند و فقط با استفاده از گیرنده‌ها و تنظیم‌کننده‌های عمومی بدون در نظر گرفتن نهایی بودن یا نبودن این فیلدها قابل دسترسی باشند.

استثناهای نادر شامل ساختارهای داده پایه است که در آن نیازی به بهبود رفتار تعیین یا بازیابی یک فیلد نیست. در چنین مواردی، فیلدها باید با استفاده از قراردادهای نامگذاری متغیرهای استاندارد، به عنوان مثال، Point.x و Point.y نامگذاری شوند.

کلاس های کاتلین می توانند ویژگی ها را آشکار کنند.

فیلدهای در معرض دید باید نهایی شوند

فیلدهای خام به شدت منع می شوند (@ به عدم افشای فیلدهای خام مراجعه کنید ). اما در شرایط نادری که یک میدان به عنوان یک میدان عمومی در معرض دید قرار می‌گیرد، آن فیلد را final کنید.

زمینه های داخلی نباید در معرض دید قرار گیرند

به نام فیلدهای داخلی در API عمومی ارجاع ندهید.

public int mFlags;

از عمومی به جای محافظت شده استفاده کنید

@ به استفاده از عمومی به جای محافظت شده مراجعه کنید

ثابت ها

اینها قوانینی در مورد ثابت های عمومی هستند.

ثابت های پرچم نباید با مقادیر int یا long همپوشانی داشته باشند

Flags به بیت هایی اشاره دارد که می توانند در مقداری اتحادیه ترکیب شوند. اگر اینطور نیست، متغیر یا 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;

برای اطلاعات بیشتر در مورد تعریف ثابت های پرچم عمومی برای پرچم های بیت ماسک @IntDef را ببینید.

ثابت های نهایی استاتیک باید از قرارداد نامگذاری تمام کلاهک، زیرخط جدا شده استفاده کنند

تمام کلمات ثابت باید با حروف بزرگ نوشته شوند و چند کلمه با _ از هم جدا شوند. به عنوان مثال:

public static final int fooThing = 5

public static final int FOO_THING = 5

از پیشوندهای استاندارد برای ثابت ها استفاده کنید

بسیاری از ثابت های استفاده شده در اندروید برای چیزهای استاندارد مانند پرچم ها، کلیدها و اکشن ها هستند. این ثابت ها باید دارای پیشوندهای استاندارد باشند تا به عنوان این چیزها بیشتر قابل شناسایی باشند.

به عنوان مثال، موارد اضافی قصد باید با EXTRA_ شروع شود. اقدامات هدف باید با ACTION_ شروع شود. ثابت های مورد استفاده با Context.bindService() باید با BIND_ شروع شوند.

نام‌ها و دامنه‌های ثابت کلیدی

مقادیر ثابت رشته باید با نام ثابت مطابقت داشته باشد و عموماً باید در محدوده بسته یا دامنه باشد. به عنوان مثال:

public static final String FOO_THING = "foo"

نه به طور مداوم نامگذاری شده است و نه به طور مناسب محدوده. در عوض، در نظر بگیرید:

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

پیشوندهای android در ثابت های رشته محدوده برای پروژه منبع باز Android رزرو شده است.

کنش‌ها و موارد اضافی، و همچنین ورودی‌های Bundle، باید با استفاده از نام بسته‌ای که در داخل آن تعریف شده‌اند، فضای نامی داشته باشند.

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

از عمومی به جای محافظت شده استفاده کنید

@ به استفاده از عمومی به جای محافظت شده مراجعه کنید

از پیشوندهای ثابت استفاده کنید

ثابت های مرتبط باید همه با یک پیشوند شروع شوند. به عنوان مثال، برای مجموعه ای از ثابت ها برای استفاده با مقادیر پرچم:

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;

@ به استفاده از پیشوندهای استاندارد برای ثابت ها مراجعه کنید

از نام منابع ثابت استفاده کنید

شناسه‌ها، ویژگی‌ها و مقادیر عمومی باید با استفاده از قرارداد نام‌گذاری camelCase نام‌گذاری شوند، برای مثال @id/accessibilityActionPageUp یا @attr/textAppearance ، مشابه فیلدهای عمومی در جاوا.

در برخی موارد، یک شناسه یا ویژگی عمومی شامل یک پیشوند مشترک است که با زیرخط جدا شده است:

• مقادیر پیکربندی پلتفرم مانند @string/config_recentsComponentName در config.xml
• ویژگی های نمای خاص چیدمان مانند @attr/layout_marginStart در attrs.xml

تم ها و سبک های عمومی باید از قرارداد نامگذاری سلسله مراتبی PascalCase پیروی کنند، برای مثال @style/Theme.Material.Light.DarkActionBar یا @style/Widget.Material.SearchView.ActionBar ، مشابه کلاس های تودرتو در جاوا.

طرح‌بندی و منابع قابل ترسیم نباید به‌عنوان APIهای عمومی در معرض دید قرار گیرند. با این حال، اگر باید در معرض دید قرار گیرند، طرح‌بندی‌ها و نقشه‌های عمومی باید با استفاده از قرارداد نام‌گذاری under_score نام‌گذاری شوند، برای مثال layout/simple_list_item_1.xml یا drawable/title_bar_tall.xml .

هنگامی که ثابت ها می توانند تغییر کنند، آنها را پویا کنید

کامپایلر ممکن است مقادیر ثابت را درون خطی قرار دهد، بنابراین حفظ مقادیر یکسان بخشی از قرارداد API در نظر گرفته می شود. اگر مقدار یک ثابت MIN_FOO یا MAX_FOO ممکن است در آینده تغییر کند، به جای آن روش‌های پویا را در نظر بگیرید.

CameraManager.MAX_CAMERAS

CameraManager.getMaxCameras()

سازگاری فوروارد را برای تماس‌های برگشتی در نظر بگیرید

ثابت‌های تعریف‌شده در نسخه‌های API آینده برای برنامه‌هایی که APIهای قدیمی‌تر را هدف قرار می‌دهند، شناخته شده نیستند. به همین دلیل، ثابت‌های ارائه‌شده به برنامه‌ها باید نسخه API هدف برنامه را در نظر بگیرند و ثابت‌های جدیدتر را به یک مقدار ثابت ترسیم کنند. سناریوی زیر را در نظر بگیرید:

منبع SDK فرضی:

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

برنامه فرضی با targetSdkVersion="22" :

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

در این مورد، برنامه با محدودیت های سطح 22 API طراحی شده بود و یک فرض معقول (تا حدودی) ایجاد کرد که تنها دو حالت ممکن وجود دارد. با این حال، اگر برنامه STATUS_FAILURE_RETRY جدید اضافه شده را دریافت کند، این را به عنوان موفقیت تفسیر می کند.

روش‌هایی که ثابت‌ها را برمی‌گردانند، می‌توانند با محدود کردن خروجی خود برای مطابقت با سطح API مورد نظر برنامه، مواردی مانند این را با خیال راحت مدیریت کنند:

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

توسعه دهندگان نمی توانند پیش بینی کنند که آیا لیستی از ثابت ها ممکن است در آینده تغییر کند یا خیر. اگر یک API را با یک ثابت UNKNOWN یا UNSPECIFIED تعریف کنید که شبیه به همه چیز است، توسعه‌دهندگان فرض می‌کنند که ثابت‌های منتشر شده هنگام نوشتن برنامه‌شان جامع هستند. اگر مایل به تنظیم این انتظار نیستید، مجدداً در نظر بگیرید که آیا ثابت کردن همه چیز ایده خوبی برای API شما است یا خیر.

علاوه بر این، کتابخانه ها نمی توانند targetSdkVersion خود را جدا از برنامه مشخص کنند و مدیریت تغییرات رفتار targetSdkVersion از کد کتابخانه پیچیده و مستعد خطا است.

عدد صحیح یا ثابت رشته

اگر فضای نام مقادیر در خارج از بسته شما قابل توسعه نیست، از ثابت های عدد صحیح و @IntDef استفاده کنید. اگر فضای نام مشترک است یا می توان آن را با کد خارج از بسته شما گسترش داد، از ثابت های رشته استفاده کنید.

کلاس های داده

کلاس‌های داده مجموعه‌ای از ویژگی‌های تغییرناپذیر را نشان می‌دهند و مجموعه کوچک و مشخصی از توابع کاربردی را برای تعامل با آن داده ارائه می‌دهند.

data class در API های عمومی Kotlin استفاده نکنید ، زیرا کامپایلر Kotlin API زبان یا سازگاری باینری را برای کدهای تولید شده تضمین نمی کند. در عوض، توابع مورد نیاز را به صورت دستی پیاده سازی کنید.

نمونه سازی

در جاوا، کلاس‌های داده باید زمانی که ویژگی‌های کمی وجود دارد یک سازنده ارائه دهند یا زمانی که ویژگی‌های زیادی وجود دارد از الگوی Builder استفاده کنند.

در کاتلین، کلاس‌های داده باید یک سازنده با آرگومان‌های پیش‌فرض بدون توجه به تعداد ویژگی‌ها ارائه کنند. کلاس های داده تعریف شده در Kotlin همچنین ممکن است از ارائه سازنده هنگام هدف قرار دادن مشتریان جاوا بهره مند شوند.

اصلاح و کپی

در مواردی که داده ها نیاز به اصلاح دارند، یک کلاس Builder با سازنده کپی (جاوا) یا یک تابع عضو copy() (Kotlin) ارائه دهید که یک شی جدید را برمی گرداند.

هنگام ارائه یک تابع copy() در Kotlin، آرگومان‌ها باید با سازنده کلاس مطابقت داشته باشند و پیش‌فرض‌ها باید با استفاده از مقادیر فعلی شی پر شوند:

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

رفتارهای اضافی

کلاس های داده باید هم equals() و hashCode() پیاده سازی کنند و هر ویژگی باید در پیاده سازی این متدها در نظر گرفته شود.

کلاس‌های داده می‌توانند toString() با قالب پیشنهادی مطابق با پیاده‌سازی کلاس داده Kotlin پیاده‌سازی کنند، برای مثال User(var1=Alex, var2=42) .

روش ها

اینها قوانینی در مورد ویژگی های مختلف در متدها، پیرامون پارامترها، نام روش ها، انواع برگشتی و مشخص کننده های دسترسی هستند.

زمان

این قوانین نحوه بیان مفاهیم زمانی مانند تاریخ و مدت زمان را در APIها پوشش می دهند.

در صورت امکان، انواع java.time.* را ترجیح دهید

java.time.Duration ، java.time.Instant و بسیاری دیگر از انواع java.time.* در تمام نسخه های پلتفرم از طریق desgaring در دسترس هستند و باید هنگام بیان زمان در پارامترهای API یا مقادیر بازگشتی ترجیح داده شوند.

ترجیح می‌دهید فقط انواع یک API را نشان دهید که java.time.Duration یا java.time.Instant را می‌پذیرد یا برمی‌گرداند. Instant و از انواع اولیه با همان حالت استفاده حذف می‌شود، مگر اینکه دامنه API دامنه‌ای باشد که تخصیص شی در الگوهای استفاده در نظر گرفته شده در آن تأثیر زیادی بر عملکرد داشته باشد.

روش هایی که مدت زمان را بیان می کنند باید مدت نامگذاری شوند

اگر مقدار زمانی بیانگر مدت زمان است، پارامتر را "دوره" نامگذاری کنید نه "زمان".

ValueAnimator.setTime(java.time.Duration);

ValueAnimator.setDuration(java.time.Duration);

استثنائات:

"تایم اوت" زمانی مناسب است که مدت زمان به طور خاص برای یک مقدار مهلت زمانی اعمال شود.

"time" با یک نوع java.time.Instant زمانی مناسب است که به یک نقطه خاص در زمان اشاره شود، نه مدت زمان.

روش هایی که مدت زمان یا زمان را به صورت اولیه بیان می کنند باید با واحد زمان نامگذاری شوند و از long استفاده شوند

روش‌هایی که مدت زمان‌ها را به‌عنوان ابتدایی می‌پذیرند یا برمی‌گردانند، باید نام روش را با واحدهای زمانی مرتبط (مانند Millis ، Nanos ، Seconds ) پسوند کنند تا نام تزئین‌نشده برای استفاده با java.time.Duration ذخیره شود. زمان را ببینید.

روش ها همچنین باید به طور مناسب با واحد و مبنای زمانی خود حاشیه نویسی شوند:

• @CurrentTimeMillisLong : مقدار یک مهر زمانی غیرمنفی است که به عنوان تعداد میلی ثانیه از سال 1970-01-01T00:00:00Z اندازه گیری می شود.
• @CurrentTimeSecondsLong : مقدار یک مُهر زمانی غیرمنفی است که به‌عنوان تعداد ثانیه‌ها از 1970-01-01T00:00:00Z اندازه‌گیری می‌شود.
• @DurationMillisLong : مقدار یک مدت زمان غیرمنفی بر حسب میلی ثانیه است.
• @ElapsedRealtimeLong : Value یک مهر زمانی غیرمنفی در پایگاه زمانی SystemClock.elapsedRealtime() است.
• @UptimeMillisLong : مقدار یک مهر زمانی غیرمنفی در پایگاه زمانی SystemClock.uptimeMillis() است.

پارامترهای زمان اولیه یا مقادیر بازگشتی باید long و نه int استفاده کنند.

ValueAnimator.setDuration(@DurationMillisLong long);

ValueAnimator.setDurationNanos(long);

روش‌هایی که واحدهای زمان را بیان می‌کنند باید کوتاه‌نویسی غیر اختصاری را برای نام واحدها ترجیح دهند

public void setIntervalNs(long intervalNs);

public void setTimeoutUs(long timeoutUs);

public void setIntervalNanos(long intervalNanos);

public void setTimeoutMicros(long timeoutMicros);

استدلال های طولانی مدت را حاشیه نویسی کنید

این پلت فرم شامل چندین حاشیه نویسی برای ارائه تایپ قوی تر برای واحدهای زمانی long است:

• @CurrentTimeMillisLong : مقدار یک مهر زمانی غیرمنفی است که به عنوان تعداد میلی ثانیه از 1970-01-01T00:00:00Z اندازه گیری می شود، بنابراین در پایگاه زمانی System.currentTimeMillis() است.
• @CurrentTimeSecondsLong : مقدار یک مُهر زمانی غیرمنفی است که به‌عنوان تعداد ثانیه‌ها از 1970-01-01T00:00:00Z اندازه‌گیری می‌شود.
• @DurationMillisLong : مقدار یک مدت زمان غیرمنفی بر حسب میلی ثانیه است.
• @ElapsedRealtimeLong : Value یک مهر زمانی غیرمنفی در پایگاه زمانی SystemClock#elapsedRealtime() است.
• @UptimeMillisLong : مقدار یک مهر زمانی غیرمنفی در پایگاه زمانی SystemClock#uptimeMillis() است.

واحدهای اندازه گیری

برای همه روش هایی که واحد اندازه گیری غیر از زمان را بیان می کنند، پیشوندهای واحد CamelCased SI را ترجیح دهید.

public  long[] getFrequenciesKhz();

public  float getStreamVolumeDb();

پارامترهای اختیاری را در پایان اضافه بارها قرار دهید

اگر روشی با پارامترهای اختیاری اضافه بار دارید، آن پارامترها را در انتها نگه دارید و با سایر پارامترها مرتب کنید:

public int doFoo(boolean flag);

public int doFoo(int id, boolean flag);

public int doFoo(boolean flag);

public int doFoo(boolean flag, int id);

هنگام اضافه کردن بارهای اضافه برای آرگومان های اختیاری، رفتار روش های ساده تر باید دقیقاً به همان شکلی باشد که گویی آرگومان های پیش فرض برای روش های دقیق تر ارائه شده است.

نتیجه: اگر روش چند شکلی است، روش‌های دیگری را اضافه نکنید، مگر اینکه آرگومان‌های اختیاری را اضافه کنید یا انواع مختلف آرگومان‌ها را بپذیرید. اگر روش overloaded کاری اساساً متفاوت انجام می دهد، نام جدیدی به آن بدهید.

روش‌های دارای پارامترهای پیش‌فرض باید با @JvmOverloads حاشیه‌نویسی شوند (فقط Kotlin)

متدها و سازنده‌های دارای پارامترهای پیش‌فرض باید با @JvmOverloads حاشیه‌نویسی شوند تا سازگاری باینری حفظ شود.

برای جزئیات بیشتر، اضافه‌بارهای عملکرد را برای پیش‌فرض‌ها در راهنمای رسمی interop Kotlin-Java ببینید.

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

مقادیر پارامترهای پیش فرض را حذف نکنید (فقط Kotlin)

اگر روشی با پارامتری با مقدار پیش‌فرض ارسال شده باشد، حذف مقدار پیش‌فرض یک تغییر مبهم است.

متمایزترین و مشخص ترین پارامترهای روش باید ابتدا باشند

اگر روشی با چند پارامتر دارید، ابتدا مرتبط ترین آنها را قرار دهید. پارامترهایی که پرچم‌ها و گزینه‌های دیگر را مشخص می‌کنند، نسبت به پارامترهایی که شی مورد نظر را توصیف می‌کنند، اهمیت کمتری دارند. اگر یک تماس تکمیلی وجود دارد، آن را آخرین بار قرار دهید.

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

همچنین نگاه کنید به: قرار دادن پارامترهای اختیاری در پایان در اضافه بار

سازندگان

الگوی Builder برای ایجاد اشیاء پیچیده جاوا توصیه می شود و معمولاً در اندروید برای موارد زیر استفاده می شود:

• ویژگی های شی حاصل باید تغییرناپذیر باشد
• تعداد زیادی ویژگی مورد نیاز وجود دارد، به عنوان مثال بسیاری از آرگومان های سازنده
• یک رابطه پیچیده بین خواص در زمان ساخت وجود دارد، به عنوان مثال یک مرحله تأیید لازم است. توجه داشته باشید که این سطح از پیچیدگی اغلب نشان دهنده مشکلاتی در قابلیت استفاده API است.

در نظر بگیرید که آیا به سازنده نیاز دارید یا خیر. سازندگان در سطح API مفید هستند اگر از موارد زیر استفاده کنند:

• تنها تعداد کمی از یک مجموعه بالقوه بزرگ از پارامترهای ایجاد اختیاری را پیکربندی کنید
• بسیاری از پارامترهای ایجاد اختیاری یا مورد نیاز مختلف را پیکربندی کنید، گاهی اوقات از انواع مشابه یا مشابه، که در غیر این صورت سایت های تماس ممکن است خواندن گیج کننده یا مستعد خطا برای نوشتن شوند.
• ایجاد یک شی را به صورت تدریجی پیکربندی کنید، جایی که چندین قطعه مختلف کد پیکربندی ممکن است هر کدام به عنوان جزئیات پیاده سازی با سازنده تماس بگیرند.
• با افزودن پارامترهای ایجاد اختیاری اضافی در نسخه‌های API آینده، به یک نوع اجازه دهید رشد کند

اگر یک نوع با سه یا کمتر پارامتر مورد نیاز و بدون پارامتر اختیاری دارید، تقریباً همیشه می‌توانید از یک سازنده صرفنظر کنید و از یک سازنده ساده استفاده کنید.

کلاس های منبع کاتلین باید سازنده های حاشیه نویسی @JvmOverloads با آرگومان های پیش فرض را به سازندگان ترجیح دهند، اما ممکن است با ارائه Builders در مواردی که قبلا ذکر شد، قابلیت استفاده را برای مشتریان جاوا بهبود بخشند.

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

کلاس های سازنده باید سازنده را برگردانند

کلاس های سازنده باید با برگرداندن شی Builder (مانند this ) از هر متد به جز build() زنجیره متد را فعال کنند. اشیاء ساخته شده اضافی باید به عنوان آرگومان ارسال شوند -- سازنده شی دیگری را برنگردانید . به عنوان مثال:

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

در موارد نادری که یک کلاس سازنده پایه باید پسوند را پشتیبانی کند، از یک نوع بازگشت عمومی استفاده کنید:

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

کلاس های سازنده باید از طریق سازنده ایجاد شوند

برای حفظ یکنواختی ایجاد سازنده از طریق سطح API Android، همه سازندگان باید از طریق یک سازنده و نه یک روش ایجاد کننده ایستا ایجاد شوند. برای API های مبتنی بر Kotlin، Builder باید عمومی باشد حتی اگر انتظار می رود کاربران Kotlin به طور ضمنی به سازنده از طریق مکانیزم ایجاد روش کارخانه/ سبک DSL اعتماد کنند. کتابخانه‌ها نباید از @PublishedApi internal برای مخفی کردن انتخابی سازنده کلاس Builder از کلاینت‌های Kotlin استفاده کنند.

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

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

همه آرگومان‌های سازنده سازنده باید مورد نیاز باشند (مانند @NonNull)

اختیاری، برای مثال @Nullable ، آرگومان ها باید به متدهای تنظیم کننده منتقل شوند. سازنده سازنده باید یک NullPointerException پرتاب کند (استفاده از Objects.requireNonNull را در نظر بگیرید) اگر آرگومان مورد نیاز مشخص نشده باشد.

کلاس های سازنده باید کلاس های داخلی استاتیک نهایی از انواع ساخته شده خود باشند

به خاطر سازماندهی منطقی در یک بسته، کلاس‌های سازنده معمولاً باید به‌عنوان کلاس‌های داخلی نهایی انواع ساخته‌شده‌شان، برای مثال Tone.Builder به جای ToneBuilder در معرض دید قرار گیرند.

سازندگان ممکن است شامل یک سازنده برای ایجاد یک نمونه جدید از یک نمونه موجود باشند

سازندگان ممکن است شامل یک سازنده کپی برای ایجاد یک نمونه سازنده جدید از یک سازنده یا شی ساخته شده موجود باشند. آنها نباید روش های جایگزین برای ایجاد نمونه های سازنده از سازندگان موجود یا ساخت اشیاء ارائه دهند.

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

اگر سازنده سازنده کپی داشته باشد، تنظیم‌کننده‌های سازنده باید آرگومان‌های Nullable@ را بگیرند

اگر ممکن است یک نمونه جدید از سازنده از یک نمونه موجود ایجاد شود، بازنشانی ضروری است. اگر سازنده کپی در دسترس نباشد، سازنده ممکن است آرگومان های @Nullable یا @NonNullable داشته باشد.

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

تنظیم‌کننده‌های سازنده ممکن است آرگومان‌های @Nullable را برای ویژگی‌های اختیاری بگیرند

معمولاً استفاده از یک مقدار nullable برای ورودی درجه دوم ساده‌تر است، به خصوص در Kotlin، که از آرگومان‌های پیش‌فرض به جای سازنده‌ها و اضافه‌بارها استفاده می‌کند.

علاوه بر این، تنظیم‌کننده‌های @Nullable آن‌ها را با دریافت‌کننده‌هایشان مطابقت می‌دهند، که برای ویژگی‌های اختیاری باید @Nullable باشد.

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

استفاده رایج در Kotlin:

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

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

مقدار پیش‌فرض (اگر تنظیم‌کننده فراخوانی نشده باشد)، و معنای null ، باید به‌درستی در تنظیم‌کننده و دریافت‌کننده ثبت شوند.

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

تنظیم‌کننده‌های سازنده را می‌توان برای ویژگی‌های قابل تغییر در جایی که تنظیم‌کننده‌ها در کلاس ساخته شده در دسترس هستند، ارائه کرد

اگر کلاس شما دارای ویژگی های قابل تغییر است و به کلاس Builder نیاز دارد، ابتدا از خود بپرسید که آیا کلاس شما واقعاً باید ویژگی های قابل تغییر داشته باشد یا خیر.

در مرحله بعد، اگر مطمئن هستید که به ویژگی های قابل تغییر نیاز دارید، تصمیم بگیرید که کدام یک از سناریوهای زیر برای مورد استفاده مورد انتظار شما بهتر عمل می کند:

1. شی ساخته شده باید فورا قابل استفاده باشد، بنابراین تنظیم کننده ها باید برای همه ویژگی های مرتبط، اعم از تغییرپذیر یا غیرقابل تغییر، ارائه شوند.

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

2. ممکن است قبل از اینکه شی ساخته شده مفید باشد، نیاز به انجام برخی فراخوانی های اضافی باشد، بنابراین تنظیم کننده ها نباید برای ویژگی های قابل تغییر ارائه شوند.

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

این دو سناریو را با هم مخلوط نکنید.

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

سازندگان نباید گیرنده داشته باشند

Getter باید روی شی ساخته شده باشد، نه سازنده.

تنظیم کننده های سازنده باید گیرنده های مربوطه را در کلاس ساخته شده داشته باشند

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

نامگذاری متد سازنده

نام متدهای سازنده باید از سبک setFoo() ، addFoo() یا clearFoo() استفاده کند.

از کلاس های سازنده انتظار می رود که متد build() را اعلام کنند

کلاس های سازنده باید یک متد build() را اعلام کنند که نمونه ای از شی ساخته شده را برمی گرداند.

متدهای build() باید اشیاء @NonNull را برگردانند

انتظار می رود متد build() سازنده یک نمونه غیر تهی از شی ساخته شده را برگرداند. در صورتی که شیء به دلیل پارامترهای نامعتبر ایجاد نشود، اعتبارسنجی را می توان به روش ساخت موکول کرد و یک IllegalStateException باید پرتاب شود.

قفل های داخلی را در معرض دید قرار ندهید

روش‌ها در API عمومی نباید از کلمه کلیدی synchronized استفاده کنند. این کلمه کلیدی باعث می شود از شی یا کلاس شما به عنوان قفل استفاده شود، و چون در معرض دیگران قرار می گیرد، اگر کد دیگری خارج از کلاس شما شروع به استفاده از آن برای مقاصد قفل کند، ممکن است با عوارض جانبی غیرمنتظره مواجه شوید.

در عوض، هر قفل مورد نیاز را در برابر یک شی داخلی و خصوصی انجام دهید.

public synchronized void doThing() { ... }

private final Object mThingLock = new Object();

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

روش‌های مبتنی بر Accessor باید از دستورالعمل‌های ویژگی Kotlin پیروی کنند

هنگامی که از منابع Kotlin مشاهده می‌شود، روش‌های دارای سبک دسترسی - آنهایی که از پیشوندهای get ، set یا is استفاده می‌کنند، به‌عنوان ویژگی‌های Kotlin نیز در دسترس خواهند بود. برای مثال، int getField() تعریف شده در جاوا در Kotlin به عنوان val field: Int .

به همین دلیل، و به طور کلی برای برآورده کردن انتظارات توسعه‌دهندگان در مورد رفتار متد دسترسی، روش‌هایی که از پیشوندهای متد دسترسی استفاده می‌کنند باید مانند فیلدهای جاوا رفتار کنند. زمانی که:

• این روش دارای عوارض جانبی است - نام روش توصیفی تر را ترجیح دهید
• این روش شامل کار محاسباتی پرهزینه است -- compute ترجیح دهید
• این روش شامل مسدود کردن یا کارهای طولانی مدت برای برگرداندن یک مقدار، مانند IPC یا سایر ورودی/خروجی ها است - fetch ترجیح می دهند.
• متد تا زمانی که بتواند مقداری را برگرداند رشته را مسدود می‌کند - await ترجیح دهید
• این متد در هر فراخوانی یک نمونه شی جدید برمی گرداند -- ترجیح create
• این روش ممکن است با موفقیت مقداری را برنگرداند - request ترجیح دهید

توجه داشته باشید که انجام یک کار گران قیمت محاسباتی و ذخیره کردن مقدار برای تماس‌های بعدی همچنان به عنوان انجام کارهای گران قیمت محاسباتی محسوب می‌شود. جانک بین فریم ها مستهلک نمی شود.

استفاده پیشوند برای متدهای دسترسی بولی است

این قرارداد نامگذاری استاندارد برای روش ها و فیلدهای بولی در جاوا است. به طور کلی، نام متدهای بولی و متغیرها باید به عنوان سؤالاتی نوشته شوند که با مقدار بازگشتی پاسخ داده شوند.

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.

تنظیم کننده ها

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

گیرندگان

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:// Uri s. 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:

پوچ پذیری

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() (ie, 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.

منابع

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 . به عنوان مثال:

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. به عنوان مثال:

/** @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. مثال:

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. به عنوان مثال،

• 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. روش

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)

اسناد

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

روش ها

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 "eg" 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} . به عنوان مثال:

  <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 of IntDef :

• 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 Intent s 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 fun s, 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.

منسوخ شدن

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 .