摘要

• 1 前言
• 2 AS 規(guī)范
• 3 命名規(guī)范
• 4 代碼樣式規(guī)范
• 5 資源文件規(guī)范
• 6 版本統(tǒng)一規(guī)范
• 7 第三方庫(kù)規(guī)范
• 8 注釋規(guī)范
• 9 測(cè)試規(guī)范
• 10 其他的一些規(guī)范

1 前言

為了有利于項(xiàng)目維護(hù)、增強(qiáng)代碼可讀性、提升 Code Review 效率以及規(guī)范團(tuán)隊(duì)安卓開發(fā)，故提出以下安卓開發(fā)規(guī)范，該規(guī)范結(jié)合本人多年的開發(fā)經(jīng)驗(yàn)并吸取多家之精華，可謂是本人的嘔心瀝血之作，稱其為當(dāng)前最完善的安卓開發(fā)規(guī)范一點(diǎn)也不為過，如有更好建議，歡迎到 GitHub 提 issue，原文地址：Android 開發(fā)規(guī)范（完結(jié)版）。相關(guān) Demo，可以查看我的 Android 開發(fā)工具類集合項(xiàng)目：Android 開發(fā)人員不得不收集的代碼。后續(xù)可能會(huì)根據(jù)該規(guī)范出一個(gè) CheckStyle 插件來(lái)檢查是否規(guī)范，當(dāng)然也支持在 CI 上運(yùn)行。

2 AS 規(guī)范

工欲善其事，必先利其器。

1. 盡量使用最新的穩(wěn)定版的 IDE 進(jìn)行開發(fā)；
2. 編碼格式統(tǒng)一為 UTF-8；
3. 編輯完 .java、.xml 等文件后一定要 格式化，格式化，格式化（如果團(tuán)隊(duì)有公共的樣式包，那就遵循它，否則統(tǒng)一使用 AS 默認(rèn)模板即可）；
4. 刪除多余的 import，減少警告出現(xiàn)，可利用 AS 的 Optimize Imports（Settings -> Keymap -> Optimize Imports）快捷鍵；
5. Android 開發(fā)者工具可以參考這里：Android 開發(fā)者工具；

3 命名規(guī)范

代碼中的命名嚴(yán)禁使用拼音與英文混合的方式，更不允許直接使用中文的方式。正確的英文拼寫和語(yǔ)法可以讓閱讀者易于理解，避免歧義。

注意：即使純拼音命名方式也要避免采用。但 alibaba、taobao、youku、hangzhou 等國(guó)際通用的名稱，可視同英文。

3.1 包名

包名全部小寫，連續(xù)的單詞只是簡(jiǎn)單地連接起來(lái)，不使用下劃線，采用反域名命名規(guī)則，全部使用小寫字母。一級(jí)包名是頂級(jí)域名，通常為 com、edu、gov、net、org 等，二級(jí)包名為公司名，三級(jí)包名根據(jù)應(yīng)用進(jìn)行命名，后面就是對(duì)包名的劃分了，關(guān)于包名的劃分，推薦采用 PBF（按功能分包 Package By Feature），一開始我們采用的也是 PBL（按層分包 Package By Layer），很坑爹。PBF 可能不是很好區(qū)分在哪個(gè)功能中，不過也比 PBL 要好找很多，且 PBF 與 PBL 相比較有如下優(yōu)勢(shì)：

• package 內(nèi)高內(nèi)聚，package 間低耦合

  哪塊要添新功能，只改某一個(gè) package 下的東西。

  PBL 降低了代碼耦合，但帶來(lái)了 package 耦合，要添新功能，需要改 model、dbHelper、view、service 等等，需要改動(dòng)好幾個(gè) package 下的代碼，改動(dòng)的地方越多，越容易產(chǎn)生新問題，不是嗎？

  PBF 的話 featureA 相關(guān)的所有東西都在 featureA 包，feature 內(nèi)高內(nèi)聚、高度模塊化，不同 feature 之間低耦合，相關(guān)的東西都放在一起，還好找。

• package 有私有作用域（package-private scope）

  你負(fù)責(zé)開發(fā)這塊功能，這個(gè)目錄下所有東西都是你的。

  PBL 的方式是把所有工具方法都放在 util 包下，小張開發(fā)新功能時(shí)候發(fā)現(xiàn)需要一個(gè) xxUtil，但它又不是通用的，那應(yīng)該放在哪里？沒辦法，按照分層原則，我們還得放在 util 包下，好像不太合適，但放在其它包更不合適，功能越來(lái)越多，util 類也越定義越多。后來(lái)小李負(fù)責(zé)開發(fā)一塊功能時(shí)發(fā)現(xiàn)需要一個(gè) xxUtil，同樣不通用，去 util 包一看，怎么已經(jīng)有了，而且還沒法復(fù)用，只好放棄 xx 這個(gè)名字，改為 xxxUtil……，因?yàn)?PBL 的 package 沒有私有作用域，每一個(gè)包都是 public（跨包方法調(diào)用是很平常的事情，每一個(gè)包對(duì)其它包來(lái)說(shuō)都是可訪問的）；如果是 PBF，小張的 xxUtil 自然放在 featureA 下，小李的 xxUtil 在 featureB 下，如果覺得 util 好像是通用的，就去 util 包看看要不要把工具方法添進(jìn) xxUtil, class 命名沖突沒有了。

  PBF 的 package 有私有作用域，featureA 不應(yīng)該訪問 featureB 下的任何東西（如果非訪問不可，那就說(shuō)明接口定義有問題）。

• 很容易刪除功能

  統(tǒng)計(jì)發(fā)現(xiàn)新功能沒人用，這個(gè)版本那塊功能得去掉。

  如果是 PBL，得從功能入口到整個(gè)業(yè)務(wù)流程把受到牽連的所有能刪的代碼和 class 都揪出來(lái)刪掉，一不小心就完蛋。

  如果是 PBF，好說(shuō)，先刪掉對(duì)應(yīng)包，再刪掉功能入口（刪掉包后入口肯定報(bào)錯(cuò)了），完事。

• 高度抽象

  解決問題的一般方法是從抽象到具體，PBF 包名是對(duì)功能模塊的抽象，包內(nèi)的 class 是實(shí)現(xiàn)細(xì)節(jié)，符合從抽象到具體，而 PBL 弄反了。

  PBF 從確定 AppName 開始，根據(jù)功能模塊劃分 package，再考慮每塊的具體實(shí)現(xiàn)細(xì)節(jié)，而 PBL 從一開始就要考慮要不要 dao 層，要不要 com 層等等。

• 只通過 class 來(lái)分離邏輯代碼

  PBL 既分離 class 又分離 package，而 PBF 只通過 class 來(lái)分離邏輯代碼。

  沒有必要通過 package 分離，因?yàn)?PBL 中也可能出現(xiàn)尷尬的情況：

  ├── service
          ├── MainService.java
  

  按照 PBL, service 包下的所有東西都是 Service，應(yīng)該不需要 Service 后綴，但實(shí)際上通常為了方便，直接 import service 包，Service 后綴是為了避免引入的 class 和當(dāng)前包下的 class 命名沖突，當(dāng)然，不用后綴也可以，得寫清楚包路徑，比如 new com.domain.service.MainService()，麻煩；而 PBF 就很方便，無(wú)需 import，直接 new MainService() 即可。

• package 的大小有意義了

  PBL 中包的大小無(wú)限增長(zhǎng)是合理的，因?yàn)楣δ茉教碓蕉啵?PBF 中包太大（包里 class 太多）表示這塊需要重構(gòu)（劃分子包）。

如要知道更多好處，可以查看這篇博文：Package by features, not layers，當(dāng)然，我們大谷歌也有相應(yīng)的 Sample：todo-mvp，其結(jié)構(gòu)如下所示，很值得學(xué)習(xí)。

com
└── example
    └── android
        └── architecture
            └── blueprints
                └── todoapp
                    ├── BasePresenter.java
                    ├── BaseView.java
                    ├── addedittask
                    │   ├── AddEditTaskActivity.java
                    │   ├── AddEditTaskContract.java
                    │   ├── AddEditTaskFragment.java
                    │   └── AddEditTaskPresenter.java
                    ├── data
                    │   ├── Task.java
                    │   └── source
                    │       ├── TasksDataSource.java
                    │       ├── TasksRepository.java
                    │       ├── local
                    │       │   ├── TasksDbHelper.java
                    │       │   ├── TasksLocalDataSource.java
                    │       │   └── TasksPersistenceContract.java
                    │       └── remote
                    │           └── TasksRemoteDataSource.java
                    ├── statistics
                    │   ├── StatisticsActivity.java
                    │   ├── StatisticsContract.java
                    │   ├── StatisticsFragment.java
                    │   └── StatisticsPresenter.java
                    ├── taskdetail
                    │   ├── TaskDetailActivity.java
                    │   ├── TaskDetailContract.java
                    │   ├── TaskDetailFragment.java
                    │   └── TaskDetailPresenter.java
                    ├── tasks
                    │   ├── ScrollChildSwipeRefreshLayout.java
                    │   ├── TasksActivity.java
                    │   ├── TasksContract.java
                    │   ├── TasksFilterType.java
                    │   ├── TasksFragment.java
                    │   └── TasksPresenter.java
                    └── util
                        ├── ActivityUtils.java
                        ├── EspressoIdlingResource.java
                        └── SimpleCountingIdlingResource.java

參考以上的代碼結(jié)構(gòu)，按功能分包具體可以這樣做：

com
└── domain
    └── app
        ├── App.java 定義 Application 類
        ├── Config.java 定義配置數(shù)據(jù)（常量）
        ├── base 基礎(chǔ)組件
        ├── custom_view 自定義視圖
        ├── data 數(shù)據(jù)處理
        │   ├── DataManager.java 數(shù)據(jù)管理器，
        │   ├── local 來(lái)源于本地的數(shù)據(jù)，比如 SP，Database，F(xiàn)ile
        │   ├── model 定義 model（數(shù)據(jù)結(jié)構(gòu)以及 getter/setter、compareTo、equals 等等，不含復(fù)雜操作）
        │   └── remote 來(lái)源于遠(yuǎn)端的數(shù)據(jù)
        ├── feature 功能
        │   ├── feature0 功能 0
        │   │   ├── feature0Activity.java
        │   │   ├── feature0Fragment.java
        │   │   ├── xxAdapter.java
        │   │   └── ... 其他 class
        │   └── ...其他功能
        ├── injection 依賴注入
        ├── util 工具類
        └── widget 小部件

3.2 類名

類名都以 UpperCamelCase 風(fēng)格編寫。

類名通常是名詞或名詞短語(yǔ)，接口名稱有時(shí)可能是形容詞或形容詞短語(yǔ)。現(xiàn)在還沒有特定的規(guī)則或行之有效的約定來(lái)命名注解類型。

名詞，采用大駝峰命名法，盡量避免縮寫，除非該縮寫是眾所周知的， 比如 HTML、URL，如果類名稱中包含單詞縮寫，則單詞縮寫的每個(gè)字母均應(yīng)大寫。

測(cè)試類的命名以它要測(cè)試的類的名稱開始，以 Test 結(jié)束。例如：HashTest 或 HashIntegrationTest。

接口（interface）：命名規(guī)則與類一樣采用大駝峰命名法，多以 able 或 ible 結(jié)尾，如 interface Runnable、interface Accessible。

注意：如果項(xiàng)目采用 MVP，所有 Model、View、Presenter 的接口都以 I 為前綴，不加后綴，其他的接口采用上述命名規(guī)則。

3.3 方法名

方法名都以 lowerCamelCase 風(fēng)格編寫。

方法名通常是動(dòng)詞或動(dòng)詞短語(yǔ)。

3.4 常量名

常量名命名模式為 CONSTANT_CASE，全部字母大寫，用下劃線分隔單詞。那到底什么算是一個(gè)常量？

每個(gè)常量都是一個(gè) static final 字段，但不是所有 static final 字段都是常量。在決定一個(gè)字段是否是一個(gè)常量時(shí)，得考慮它是否真的感覺像是一個(gè)常量。例如，如果觀測(cè)任何一個(gè)該實(shí)例的狀態(tài)是可變的，則它幾乎肯定不會(huì)是一個(gè)常量。只是永遠(yuǎn)不打算改變的對(duì)象一般是不夠的，它要真的一直不變才能將它示為常量。

// Constants
static final int NUMBER = 5;
static final ImmutableListNAMES = ImmutableList.of("Ed", "Ann");
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

// Not constants
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final SetmutableCollection = new HashSet();
static final ImmutableSetmutableElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

3.5 非常量字段名

非常量字段名以 lowerCamelCase 風(fēng)格的基礎(chǔ)上改造為如下風(fēng)格：基本結(jié)構(gòu)為 scope{Type0}VariableName{Type1}、type0VariableName{Type1}、variableName{Type1}。

說(shuō)明：{} 中的內(nèi)容為可選。

注意：所有的 VO（值對(duì)象）統(tǒng)一采用標(biāo)準(zhǔn)的 lowerCamelCase 風(fēng)格編寫，所有的 DTO（數(shù)據(jù)傳輸對(duì)象）就按照接口文檔中定義的字段名編寫。

3.5.1 scope（范圍）

非公有，非靜態(tài)字段命名以 m 開頭。

靜態(tài)字段命名以 s 開頭。

其他字段以小寫字母開頭。

例如：

public class MyClass {
    public int publicField;
    private static MyClass sSingleton;
    int mPackagePrivate;
    private int mPrivate;
    protected int mProtected;
}

使用 1 個(gè)字符前綴來(lái)表示作用范圍，1 個(gè)字符的前綴必須小寫，前綴后面是由表意性強(qiáng)的一個(gè)單詞或多個(gè)單詞組成的名字，而且每個(gè)單詞的首寫字母大寫，其它字母小寫，這樣保證了對(duì)變量名能夠進(jìn)行正確的斷句。

3.5.2 Type0（控件類型）

考慮到 Android 眾多的 UI 控件，為避免控件和普通成員變量混淆以及更好地表達(dá)意思，所有用來(lái)表示控件的成員變量統(tǒng)一加上控件縮寫作為前綴（具體見附錄 UI 控件縮寫表）。

例如：mIvAvatar、rvBooks、flContainer。

3.5.3 VariableName（變量名）

變量名中可能會(huì)出現(xiàn)量詞，我們需要?jiǎng)?chuàng)建統(tǒng)一的量詞，它們更容易理解，也更容易搜索。

例如：mFirstBook、mPreBook、curBook。

3.5.4 Type1（數(shù)據(jù)類型）

對(duì)于表示集合或者數(shù)組的非常量字段名，我們可以添加后綴來(lái)增強(qiáng)字段的可讀性，比如：

集合添加如下后綴：List、Map、Set。

數(shù)組添加如下后綴：Arr。

例如：mIvAvatarList、userArr、firstNameSet。

注意：如果數(shù)據(jù)類型不確定的話，比如表示的是很多書，那么使用其復(fù)數(shù)形式來(lái)表示也可，例如 mBooks。

3.6 參數(shù)名

參數(shù)名以 lowerCamelCase 風(fēng)格編寫，參數(shù)應(yīng)該避免用單個(gè)字符命名。

3.7 局部變量名

局部變量名以 lowerCamelCase 風(fēng)格編寫，比起其它類型的名稱，局部變量名可以有更為寬松的縮寫。

雖然縮寫更寬松，但還是要避免用單字符進(jìn)行命名，除了臨時(shí)變量和循環(huán)變量。

即使局部變量是 final 和不可改變的，也不應(yīng)該把它示為常量，自然也不能用常量的規(guī)則去命名它。

3.8 臨時(shí)變量

臨時(shí)變量通常被取名為 i、j、k、m 和 n，它們一般用于整型；c、d、e，它們一般用于字符型。 如：for (int i = 0; i < len; i++)。

3.9 類型變量名

類型變量可用以下兩種風(fēng)格之一進(jìn)行命名：

1. 單個(gè)的大寫字母，后面可以跟一個(gè)數(shù)字（如：E, T, X, T2）。
2. 以類命名方式（參考3.2 類名），后面加個(gè)大寫的 T（如：RequestT, FooBarT）。

更多還可參考：阿里巴巴 Java 開發(fā)手冊(cè)

4 代碼樣式規(guī)范

4.1 使用標(biāo)準(zhǔn)大括號(hào)樣式

左大括號(hào)不單獨(dú)占一行，與其前面的代碼位于同一行：

class MyClass {
    int func() {
        if (something) {
            // ...
        } else if (somethingElse) {
            // ...
        } else {
            // ...
        }
    }
}

我們需要在條件語(yǔ)句周圍添加大括號(hào)。例外情況：如果整個(gè)條件語(yǔ)句（條件和主體）適合放在同一行，那么您可以（但不是必須）將其全部放在一行上。例如，我們接受以下樣式：

if (condition) {
    body();
}

同樣也接受以下樣式：

if (condition) body();

但不接受以下樣式：

if (condition)
    body();  // bad!

4.2 編寫簡(jiǎn)短方法

在可行的情況下，盡量編寫短小精煉的方法。我們了解，有些情況下較長(zhǎng)的方法是恰當(dāng)?shù)模虼藢?duì)方法的代碼長(zhǎng)度沒有做出硬性限制。如果某個(gè)方法的代碼超出 40 行，請(qǐng)考慮是否可以在不破壞程序結(jié)構(gòu)的前提下對(duì)其拆解。

4.3 類成員的順序

這并沒有唯一的正確解決方案，但如果都使用一致的順序?qū)?huì)提高代碼的可讀性，推薦使用如下排序：

1. 常量
2. 字段
3. 構(gòu)造函數(shù)
4. 重寫函數(shù)和回調(diào)
5. 公有函數(shù)
6. 私有函數(shù)
7. 內(nèi)部類或接口

例如：

public class MainActivity extends Activity {

    private static final String TAG = MainActivity.class.getSimpleName();

    private String mTitle;
    private TextView mTextViewTitle;

    @Override
    public void onCreate() {
        ...
    }

    public void setTitle(String title) {
    	mTitle = title;
    }

    private void setUpView() {
        ...
    }

    static class AnInnerClass {

    }
}

如果類繼承于 Android 組件（例如 Activity 或 Fragment），那么把重寫函數(shù)按照他們的生命周期進(jìn)行排序是一個(gè)非常好的習(xí)慣，例如，Activity 實(shí)現(xiàn)了 onCreate()、onDestroy()、onPause()、onResume()，它的正確排序如下所示：

public class MainActivity extends Activity {
    //Order matches Activity lifecycle
    @Override
    public void onCreate() {}

    @Override
    public void onResume() {}

    @Override
    public void onPause() {}

    @Override
    public void onDestroy() {}
}

4.4 函數(shù)參數(shù)的排序

在 Android 開發(fā)過程中，Context 在函數(shù)參數(shù)中是再常見不過的了，我們最好把 Context 作為其第一個(gè)參數(shù)。

正相反，我們把回調(diào)接口應(yīng)該作為其最后一個(gè)參數(shù)。

例如：

// Context always goes first
public User loadUser(Context context, int userId);

// Callbacks always go last
public void loadUserAsync(Context context, int userId, UserCallback callback);

4.5 字符串常量的命名和值

Android SDK 中的很多類都用到了鍵值對(duì)函數(shù)，比如 SharedPreferences、Bundle、Intent，所以，即便是一個(gè)小應(yīng)用，我們最終也不得不編寫大量的字符串常量。

當(dāng)時(shí)用到這些類的時(shí)候，我們 必須 將它們的鍵定義為 static final 字段，并遵循以下指示作為前綴。

說(shuō)明：雖然 Fragment.getArguments() 得到的也是 Bundle ，但因?yàn)檫@是 Bundle 的常用用法，所以特意為此定義一個(gè)不同的前綴。

例如：

// 注意：字段的值與名稱相同以避免重復(fù)問題
static final String PREF_EMAIL = "PREF_EMAIL";
static final String BUNDLE_AGE = "BUNDLE_AGE";
static final String ARGUMENT_USER_ID = "ARGUMENT_USER_ID";

// 與意圖相關(guān)的項(xiàng)使用完整的包名作為值的前綴
static final String EXTRA_SURNAME = "com.myapp.extras.EXTRA_SURNAME";
static final String ACTION_OPEN_USER = "com.myapp.action.ACTION_OPEN_USER";

4.6 Activities 和 Fragments 的傳參

當(dāng) Activity 或 Fragment 傳遞數(shù)據(jù)通過 Intent 或 Bundle 時(shí)，不同值的鍵須遵循上一條所提及到的。

當(dāng) Activity 或 Fragment 啟動(dòng)需要傳遞參數(shù)時(shí)，那么它需要提供一個(gè) public static 的函數(shù)來(lái)幫助啟動(dòng)或創(chuàng)建它。

這方面，AS 已幫你寫好了相關(guān)的 Live Templates，啟動(dòng)相關(guān) Activity 的只需要在其內(nèi)部輸入 starter 即可生成它的啟動(dòng)器，如下所示：

public static void start(Context context, User user) {
      Intent starter = new Intent(context, MainActivity.class);
      starter.putParcelableExtra(EXTRA_USER, user);
      context.startActivity(starter);
}

同理，啟動(dòng)相關(guān) Fragment 在其內(nèi)部輸入 newInstance 即可，如下所示：

public static MainFragment newInstance(User user) {
      Bundle args = new Bundle();
      args.putParcelable(ARGUMENT_USER, user);
      MainFragment fragment = new MainFragment();
      fragment.setArguments(args);
      return fragment;
}

注意：這些函數(shù)需要放在 onCreate() 之前的類的頂部；如果我們使用了這種方式，那么 extras 和 arguments 的鍵應(yīng)該是 private 的，因?yàn)樗鼈儾辉傩枰┞督o其他類來(lái)使用。

4.7 行長(zhǎng)限制

代碼中每一行文本的長(zhǎng)度都應(yīng)該不超過 100 個(gè)字符。雖然關(guān)于此規(guī)則存在很多爭(zhēng)論，但最終決定仍是以 100 個(gè)字符為上限，如果行長(zhǎng)超過了 100（AS 窗口右側(cè)的豎線就是設(shè)置的行寬末尾 ），我們通常有兩種方法來(lái)縮減行長(zhǎng)。

• 提取一個(gè)局部變量或方法（最好）。
• 使用換行符將一行換成多行。

不過存在以下例外情況：

• 如果備注行包含長(zhǎng)度超過 100 個(gè)字符的示例命令或文字網(wǎng)址，那么為了便于剪切和粘貼，該行可以超過 100 個(gè)字符。
• 導(dǎo)入語(yǔ)句行可以超出此限制，因?yàn)橛脩艉苌贂?huì)看到它們（這也簡(jiǎn)化了工具編寫流程）。

4.7.1 換行策略

這沒有一個(gè)準(zhǔn)確的解決方案來(lái)決定如何換行，通常不同的解決方案都是有效的，但是有一些規(guī)則可以應(yīng)用于常見的情況。

4.7.1.1 操作符的換行

除賦值操作符之外，我們把換行符放在操作符之前，例如：

int longName = anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne
        + theFinalOne;

賦值操作符的換行我們放在其后，例如：

int longName =
        anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne + theFinalOne;

4.7.1.2 函數(shù)鏈的換行

當(dāng)同一行中調(diào)用多個(gè)函數(shù)時(shí)（比如使用構(gòu)建器時(shí)），對(duì)每個(gè)函數(shù)的調(diào)用應(yīng)該在新的一行中，我們把換行符插入在 . 之前。

例如：

Picasso.with(context).load("https://blankj.com/images/avatar.jpg").into(ivAvatar);

我們應(yīng)該使用如下規(guī)則：

Picasso.with(context)
        .load("https://blankj.com/images/avatar.jpg")
        .into(ivAvatar);

4.7.1.3 多參數(shù)的換行

當(dāng)一個(gè)方法有很多參數(shù)或者參數(shù)很長(zhǎng)的時(shí)候，我們應(yīng)該在每個(gè) , 后面進(jìn)行換行。

比如：

loadPicture(context, "https://blankj.com/images/avatar.jpg", ivAvatar, "Avatar of the user", clickListener);

我們應(yīng)該使用如下規(guī)則：

loadPicture(context,
        "https://blankj.com/images/avatar.jpg",
        ivAvatar,
        "Avatar of the user",
        clickListener);

4.7.1.4 RxJava 鏈?zhǔn)降膿Q行

RxJava 的每個(gè)操作符都需要換新行，并且把換行符插入在 . 之前。

例如：

public Observable<Location> syncLocations() {
    return mDatabaseHelper.getAllLocations()
            .concatMap(new Func1<Location, Observable<? extends Location>>() {
                @Override
                 public Observable<? extends Location> call(Location location) {
                     return mRetrofitService.getLocation(location.id);
                 }
            })
            .retry(new Func2<Integer, Throwable, Boolean>() {
                 @Override
                 public Boolean call(Integer numRetries, Throwable throwable) {
                     return throwable instanceof RetrofitError;
                 }
            });
}

5 資源文件規(guī)范

資源文件命名為全部小寫，采用下劃線命名法。

如果是組件化開發(fā)，我們可以在組件和公共模塊間創(chuàng)建一個(gè) ui 模塊來(lái)專門存放資源文件，然后讓每個(gè)組件都依賴 ui 模塊。這樣做的好處是如果老項(xiàng)目要實(shí)現(xiàn)組件化的話，只需把資源文件都放入 ui 模塊即可，如果想對(duì)資源文件進(jìn)行分包，可以參考我這篇文章：Android Studio 下對(duì)資源進(jìn)行分包；還避免了多個(gè)模塊間資源不能復(fù)用的問題。

如果是三方庫(kù)開發(fā)，其使用到的資源文件及相關(guān)的 name 都應(yīng)該使用庫(kù)名作為前綴，這樣做可以避免三方庫(kù)資源和實(shí)際應(yīng)用資源重名的沖突。

5.1 動(dòng)畫資源文件（anim/ 和 animator/）

安卓主要包含屬性動(dòng)畫和視圖動(dòng)畫，其視圖動(dòng)畫包括補(bǔ)間動(dòng)畫和逐幀動(dòng)畫。屬性動(dòng)畫文件需要放在 res/animator/ 目錄下，視圖動(dòng)畫文件需放在 res/anim/ 目錄下。

命名規(guī)則：{模塊名_}邏輯名稱。

說(shuō)明：{} 中的內(nèi)容為可選，邏輯名稱 可由多個(gè)單詞加下劃線組成。

例如：refresh_progress.xml、market_cart_add.xml、market_cart_remove.xml。

如果是普通的補(bǔ)間動(dòng)畫或者屬性動(dòng)畫，可采用：動(dòng)畫類型_方向 的命名方式。

例如：

5.2 顏色資源文件（color/）

專門存放顏色相關(guān)的資源文件。

命名規(guī)則：類型{_模塊名}_邏輯名稱。

說(shuō)明：{} 中的內(nèi)容為可選。

例如：sel_btn_font.xml。

顏色資源也可以放于 res/drawable/ 目錄，引用時(shí)則用 @drawable 來(lái)引用，但不推薦這么做，最好還是把兩者分開。

5.3 圖片資源文件（drawable/ 和 mipmap/）

res/drawable/ 目錄下放的是位圖文件（.png、.9.png、.jpg、.gif）或編譯為可繪制對(duì)象資源子類型的 XML 文件，而 res/mipmap/ 目錄下放的是不同密度的啟動(dòng)圖標(biāo)，所以 res/mipmap/ 只用于存放啟動(dòng)圖標(biāo)，其余圖片資源文件都應(yīng)該放到 res/drawable/ 目錄下。

命名規(guī)則：類型{_模塊名}_邏輯名稱、類型{_模塊名}_顏色。

說(shuō)明：{} 中的內(nèi)容為可選；類型 可以是可繪制對(duì)象資源類型，也可以是控件類型（具體見附錄UI 控件縮寫表）；最后可加后綴 _small 表示小圖，_big 表示大圖。

例如：

如果有多種形態(tài)，如按鈕選擇器：sel_btn_xx.xml，采用如下命名：

注意：使用 Android Studio 的插件 SelectorChapek 可以快速生成 selector，前提是命名要規(guī)范。

5.4 布局資源文件（layout/）

命名規(guī)則：類型_模塊名、類型{_模塊名}_邏輯名稱。

說(shuō)明：{} 中的內(nèi)容為可選。

例如：

5.5 菜單資源文件（menu/）

菜單相關(guān)的資源文件應(yīng)放在該目錄下。

命名規(guī)則：{模塊名_}邏輯名稱

說(shuō)明：{} 中的內(nèi)容為可選。

例如：main_drawer.xml、navigation.xml。

5.6 values 資源文件（values/）

values/ 資源文件下的文件都以 s 結(jié)尾，如 attrs.xml、colors.xml、dimens.xml，起作用的不是文件名稱，而是 <resources> 標(biāo)簽下的各種標(biāo)簽，比如 <style> 決定樣式，<color> 決定顏色，所以，可以把一個(gè)大的 xml 文件分割成多個(gè)小的文件，比如可以有多個(gè) style 文件，如 styles.xml、styles_home.xml、styles_item_details.xml、styles_forms.xml。

5.6.1 colors.xml

<color> 的 name 命名使用下劃線命名法，在你的 colors.xml 文件中應(yīng)該只是映射顏色的名稱一個(gè) ARGB 值，而沒有其它的。不要使用它為不同的按鈕來(lái)定義 ARGB 值。

例如，不要像下面這樣做：

  <resources>
      <color name="button_foreground">#FFFFFF</color>
      <color name="button_background">#2A91BD</color>
      <color name="comment_background_inactive">#5F5F5F</color>
      <color name="comment_background_active">#939393</color>
      <color name="comment_foreground">#FFFFFF</color>
      <color name="comment_foreground_important">#FF9D2F</color>
      ...
      <color name="comment_shadow">#323232</color>

使用這種格式，會(huì)非常容易重復(fù)定義 ARGB 值，而且如果應(yīng)用要改變基色的話會(huì)非常困難。同時(shí)，這些定義是跟一些環(huán)境關(guān)聯(lián)起來(lái)的，如 button 或者 comment，應(yīng)該放到一個(gè)按鈕風(fēng)格中，而不是在 colors.xml 文件中。

相反，應(yīng)該這樣做：

  <resources>

      <!-- grayscale -->
      <color name="white"     >#FFFFFF</color>
      <color name="gray_light">#DBDBDB</color>
      <color name="gray"      >#939393</color>
      <color name="gray_dark" >#5F5F5F</color>
      <color name="black"     >#323232</color>

      <!-- basic colors -->
      <color name="green">#27D34D</color>
      <color name="blue">#2A91BD</color>
      <color name="orange">#FF9D2F</color>
      <color name="red">#FF432F</color>

  </resources>

向應(yīng)用設(shè)計(jì)者那里要這個(gè)調(diào)色板，名稱不需要跟 "green"、"blue" 等等相同。"brand_primary"、"brand_secondary"、"brand_negative" 這樣的名字也是完全可以接受的。像這樣規(guī)范的顏色很容易修改或重構(gòu)，會(huì)使應(yīng)用一共使用了多少種不同的顏色變得非常清晰。通常一個(gè)具有審美價(jià)值的 UI 來(lái)說(shuō)，減少使用顏色的種類是非常重要的。

注意：如果某些顏色和主題有關(guān)，那就單獨(dú)寫一個(gè) colors_theme.xml。

5.6.2 dimens.xml

像對(duì)待 colors.xml 一樣對(duì)待 dimens.xml 文件，與定義顏色調(diào)色板一樣，你同時(shí)也應(yīng)該定義一個(gè)空隙間隔和字體大小的“調(diào)色板”。 一個(gè)好的例子，如下所示：

<resources>

    <!-- font sizes -->
    <dimen name="font_22">22sp</dimen>
    <dimen name="font_18">18sp</dimen>
    <dimen name="font_15">15sp</dimen>
    <dimen name="font_12">12sp</dimen>

    <!-- typical spacing between two views -->
    <dimen name="spacing_40">40dp</dimen>
    <dimen name="spacing_24">24dp</dimen>
    <dimen name="spacing_14">14dp</dimen>
    <dimen name="spacing_10">10dp</dimen>
    <dimen name="spacing_4">4dp</dimen>

    <!-- typical sizes of views -->
    <dimen name="button_height_60">60dp</dimen>
    <dimen name="button_height_40">40dp</dimen>
    <dimen name="button_height_32">32dp</dimen>

</resources>

布局時(shí)在寫 margins 和 paddings 時(shí)，你應(yīng)該使用 spacing_xx 尺寸格式來(lái)布局，而不是像對(duì)待 string 字符串一樣直接寫值，像這樣規(guī)范的尺寸很容易修改或重構(gòu)，會(huì)使應(yīng)用所有用到的尺寸一目了然。 這樣寫會(huì)非常有感覺，會(huì)使組織和改變風(fēng)格或布局非常容易。

5.6.3 strings.xml

<string> 的 name 命名使用下劃線命名法，采用以下規(guī)則：{模塊名_}邏輯名稱，這樣方便同一個(gè)界面的所有 string 都放到一起，方便查找。

5.6.4 styles.xml

<style> 的 name 命名使用大駝峰命名法，幾乎每個(gè)項(xiàng)目都需要適當(dāng)?shù)氖褂?nbsp;styles.xml 文件，因?yàn)閷?duì)于一個(gè)視圖來(lái)說(shuō)，有一個(gè)重復(fù)的外觀是很常見的，將所有的外觀細(xì)節(jié)屬性（colors、padding、font）放在 styles.xml 文件中。 在應(yīng)用中對(duì)于大多數(shù)文本內(nèi)容，最起碼你應(yīng)該有一個(gè)通用的 styles.xml 文件，例如：

<style name="ContentText">
    <item name="android:textSize">@dimen/font_normal</item>
    <item name="android:textColor">@color/basic_black</item>
</style>

應(yīng)用到 TextView 中：

<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="@string/price"
    style="@style/ContentText"
    />

或許你需要為按鈕控件做同樣的事情，不要停止在那里，將一組相關(guān)的和重復(fù) android:xxxx 的屬性放到一個(gè)通用的 <style>中。

5.7 id 命名

命名規(guī)則：view 縮寫{_模塊名}_邏輯名，例如： btn_main_search、btn_back。

如果在項(xiàng)目中有用黃油刀的話，使用 AS 的插件：ButterKnife Zelezny，可以非常方便幫助你生成注解；沒用黃油刀的話可以使用 Android Code Generator 插件。

6 版本統(tǒng)一規(guī)范

Android 開發(fā)存在著眾多版本的不同，比如 compileSdkVersion、minSdkVersion、targetSdkVersion 以及項(xiàng)目中依賴第三方庫(kù)的版本，不同的 module 及不同的開發(fā)人員都有不同的版本，所以需要一個(gè)統(tǒng)一版本規(guī)范的文件。

具體可以參考我寫的這篇博文：Android 開發(fā)之版本統(tǒng)一規(guī)范。

如果是開發(fā)多個(gè)系統(tǒng)級(jí)別的應(yīng)用，當(dāng)多個(gè)應(yīng)用同時(shí)用到相同的 so 庫(kù)時(shí)，一定要確保 so 庫(kù)的版本一致，否則可能會(huì)引發(fā)應(yīng)用崩潰。

7 第三方庫(kù)規(guī)范

別再閉門造車了，用用最新最火的技術(shù)吧，安利一波：Android 流行框架查速表，順便帶上自己的干貨：Android 開發(fā)人員不得不收集的代碼。

希望 Team 能用時(shí)下較新的技術(shù)，對(duì)開源庫(kù)的選取，一般都需要選擇比較穩(wěn)定的版本，作者在維護(hù)的項(xiàng)目，要考慮作者對(duì) issue 的解決，以及開發(fā)者的知名度等各方面。選取之后，一定的封裝是必要的。

個(gè)人推薦 Team 可使用如下優(yōu)秀輪子：

• Retrofit
• RxAndroid
• OkHttp
• Glide/Fresco
• Gson/Fastjson
• EventBus/AndroidEventBus
• GreenDao
• Dagger2（選用）
• Tinker（選用）

8 注釋規(guī)范

為了減少他人閱讀你代碼的痛苦值，請(qǐng)?jiān)陉P(guān)鍵地方做好注釋。

8.1 類注釋

每個(gè)類完成后應(yīng)該有作者姓名和聯(lián)系方式的注釋，對(duì)自己的代碼負(fù)責(zé)。

/**
 * <pre>
 *     author : Blankj
 *     e-mail : xxx@xx
 *     time   : 2017/03/07
 *     desc   : xxxx 描述
 *     version: 1.0
 * </pre>
 */
public class WelcomeActivity {
    ...
}

具體可以在 AS 中自己配制，進(jìn)入 Settings -> Editor -> File and Code Templates -> Includes -> File Header，輸入

/**
 * <pre>
 *     author : ${USER}
 *     e-mail : xxx@xx
 *     time   : ${YEAR}/${MONTH}/${DAY}
 *     desc   :
 *     version: 1.0
 * </pre>
 */

這樣便可在每次新建類的時(shí)候自動(dòng)加上該頭注釋。

8.2 方法注釋

每一個(gè)成員方法（包括自定義成員方法、覆蓋方法、屬性方法）的方法頭都必須做方法頭注釋，在方法前一行輸入 /** + 回車或者設(shè)置 Fix doc comment（Settings -> Keymap -> Fix doc comment）快捷鍵，AS 便會(huì)幫你生成模板，我們只需要補(bǔ)全參數(shù)即可，如下所示。

/**
 * bitmap 轉(zhuǎn) byteArr
 *
 * @param bitmap bitmap 對(duì)象
 * @param format 格式
 * @return 字節(jié)數(shù)組
 */
public static byte[] bitmap2Bytes(Bitmap bitmap, CompressFormat format) {
    if (bitmap == null) return null;
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
    bitmap.compress(format, 100, baos);
    return baos.toByteArray();
}

8.3 塊注釋

塊注釋與其周圍的代碼在同一縮進(jìn)級(jí)別。它們可以是 /* ... */ 風(fēng)格，也可以是 // ... 風(fēng)格（// 后最好帶一個(gè)空格）。對(duì)于多行的 /* ... */ 注釋，后續(xù)行必須從 * 開始， 并且與前一行的 * 對(duì)齊。以下示例注釋都是 OK 的。

/*
 * This is
 * okay.
 */

// And so
// is this.

/* Or you can
* even do this. */

注釋不要封閉在由星號(hào)或其它字符繪制的框架里。

Tip：在寫多行注釋時(shí)，如果你希望在必要時(shí)能重新?lián)Q行（即注釋像段落風(fēng)格一樣），那么使用 /* ... */。

8.4 其他一些注釋

AS 已幫你集成了一些注釋模板，我們只需要直接使用即可，在代碼中輸入 todo、fixme 等這些注釋模板，回車后便會(huì)出現(xiàn)如下注釋。

// TODO: 17/3/14 需要實(shí)現(xiàn)，但目前還未實(shí)現(xiàn)的功能的說(shuō)明
// FIXME: 17/3/14 需要修正，甚至代碼是錯(cuò)誤的，不能工作，需要修復(fù)的說(shuō)明

9 測(cè)試規(guī)范

業(yè)務(wù)開發(fā)完成之后，開發(fā)人員做單元測(cè)試，單元測(cè)試完成之后，保證單元測(cè)試全部通過，同時(shí)單元測(cè)試代碼覆蓋率達(dá)到一定程度（這個(gè)需要開發(fā)和測(cè)試約定，理論上越高越好），開發(fā)提測(cè)。

9.1 單元測(cè)試

測(cè)試類的名稱應(yīng)該是所測(cè)試類的名稱加 Test，我們創(chuàng)建 DatabaseHelper 的測(cè)試類，其名應(yīng)該叫 DatabaseHelperTest。

測(cè)試函數(shù)被 @Test 所注解，函數(shù)名通常以被測(cè)試的方法為前綴，然后跟隨是前提條件和預(yù)期的結(jié)果。

• 模板：void methodName 前提條件和預(yù)期結(jié)果()
• 例子：void signInWithEmptyEmailFails()

注意：如果函數(shù)足夠清晰，那么前提條件和預(yù)期的結(jié)果是可以省略的。

有時(shí)一個(gè)類可能包含大量的方法，同時(shí)需要對(duì)每個(gè)方法進(jìn)行幾次測(cè)試。在這種情況下，建議將測(cè)試類分成多個(gè)類。例如，如果 DataManager 包含很多方法，我們可能要把它分成 DataManagerSignInTest、DataManagerLoadUsersTest 等等。

9.2 Espresso 測(cè)試

每個(gè) Espresso 測(cè)試通常是針對(duì) Activity，所以其測(cè)試名就是其被測(cè)的 Activity 的名稱加 Test，比如 SignInActivityTest。

10 其他的一些規(guī)范

1. 合理布局，有效運(yùn)用 <merge>、<ViewStub>、<include> 標(biāo)簽；

2. Activity 和 Fragment 里面有許多重復(fù)的操作以及操作步驟，所以我們都需要提供一個(gè) BaseActivity 和 BaseFragment，讓所有的 Activity 和 Fragment 都繼承這個(gè)基類。

3. 方法基本上都按照調(diào)用的先后順序在各自區(qū)塊中排列；

4. 相關(guān)功能作為小區(qū)塊放在一起（或者封裝掉）；

5. 當(dāng)一個(gè)類有多個(gè)構(gòu)造函數(shù)，或是多個(gè)同名函數(shù)，這些函數(shù)應(yīng)該按順序出現(xiàn)在一起，中間不要放進(jìn)其它函數(shù)；

6. 數(shù)據(jù)提供統(tǒng)一的入口。無(wú)論是在 MVP、MVC 還是 MVVM 中，提供一個(gè)統(tǒng)一的數(shù)據(jù)入口，都可以讓代碼變得更加易于維護(hù)。比如可使用一個(gè) DataManager，把 http、preference、eventpost、database 都放在 DataManager 里面進(jìn)行操作，我們只需要與 DataManager 打交道；

7. 多用組合，少用繼承；

8. 提取方法，去除重復(fù)代碼。對(duì)于必要的工具類抽取也很重要，這在以后的項(xiàng)目中是可以重用的。

9. 可引入 Dagger2 減少模塊之間的耦合性。Dagger2 是一個(gè)依賴注入框架，使用代碼自動(dòng)生成創(chuàng)建依賴關(guān)系需要的代碼。減少很多模板化的代碼，更易于測(cè)試，降低耦合，創(chuàng)建可復(fù)用可互換的模塊；

10. 項(xiàng)目引入 RxAndroid 響應(yīng)式編程，可以極大的減少邏輯代碼；

11. 通過引入事件總線，如：EventBus、AndroidEventBus、RxBus，它允許我們?cè)?nbsp;DataLayer 中發(fā)送事件，以便 ViewLayer中的多個(gè)組件都能夠訂閱到這些事件，減少回調(diào)；

12. 盡可能使用局部變量；

13. 及時(shí)關(guān)閉流；

14. 盡量減少對(duì)變量的重復(fù)計(jì)算；

    如下面的操作：

    for (int i = 0; i < list.size(); i++) {
          ...
    }

    建議替換為：

    for (int i = 0, len = list.size(); i < len; i++) {
          ...
    }

15. 盡量采用懶加載的策略，即在需要的時(shí)候才創(chuàng)建；

    例如：

    String str = "aaa";
    if (i == 1) {
          list.add(str);
    }

    建議替換為：

    if (i == 1) {
          String str = "aaa";
          list.add(str);
    }

16. 不要在循環(huán)中使用 try…catch…，應(yīng)該把其放在最外層；

17. 使用帶緩沖的輸入輸出流進(jìn)行 IO 操作；

18. 盡量使用 HashMap、ArrayList、StringBuilder，除非線程安全需要，否則不推薦使用 HashTable、Vector、StringBuffer，后三者由于使用同步機(jī)制而導(dǎo)致了性能開銷；

19. 盡量在合適的場(chǎng)合使用單例；

    使用單例可以減輕加載的負(fù)擔(dān)、縮短加載的時(shí)間、提高加載的效率，但并不是所有地方都適用于單例，簡(jiǎn)單來(lái)說(shuō)，單例主要適用于以下三個(gè)方面：

    1. 控制資源的使用，通過線程同步來(lái)控制資源的并發(fā)訪問。

    2. 控制實(shí)例的產(chǎn)生，以達(dá)到節(jié)約資源的目的。

    3. 控制數(shù)據(jù)的共享，在不建立直接關(guān)聯(lián)的條件下，讓多個(gè)不相關(guān)的進(jìn)程或線程之間實(shí)現(xiàn)通信。

20. 把一個(gè)基本數(shù)據(jù)類型轉(zhuǎn)為字符串，基本數(shù)據(jù)類型.toString() 是最快的方式，String.valueOf(數(shù)據(jù)) 次之，數(shù)據(jù) + "" 最慢；

21. 使用 AS 自帶的 Lint 來(lái)優(yōu)化代碼結(jié)構(gòu)（什么，你不會(huì)？右鍵 module、目錄或者文件，選擇 Analyze -> Inspect Code）；

22. 最后不要忘了內(nèi)存泄漏的檢測(cè)；

最后啰嗦幾句：

• 好的命名規(guī)則能夠提高代碼質(zhì)量，使得新人加入項(xiàng)目的時(shí)候降低理解代碼的難度；
• 規(guī)矩終究是死的，適合團(tuán)隊(duì)的才是最好的；
• 命名規(guī)范需要團(tuán)隊(duì)一起齊心協(xié)力來(lái)維護(hù)執(zhí)行，在團(tuán)隊(duì)生活里，誰(shuí)都不可能獨(dú)善其身；
• 一開始可能會(huì)有些不習(xí)慣，持之以恒，總會(huì)成功的。

附錄

UI 控件縮寫表

常見的英文單詞縮寫表

程序中使用單詞縮寫原則：不要用縮寫，除非該縮寫是約定俗成的。

參考

Android 包命名規(guī)范

Android 開發(fā)最佳實(shí)踐

Android 編碼規(guī)范

阿里巴巴 Java 開發(fā)手冊(cè)

Project and code style guidelines

Google Java 編程風(fēng)格指南

小細(xì)節(jié)，大用途，35 個(gè) Java 代碼性能優(yōu)化總結(jié)！

版本日志

• 17/12/08: 新增組件化和三方庫(kù)開發(fā)資源文件規(guī)范；
• 17/12/05: 新增 logo；
• 17/12/04: 完善按功能分包，修復(fù) typo，定該版為完結(jié)版；
• 17/12/03: 完善代碼樣式規(guī)范和測(cè)試規(guī)范；
• 17/12/02: 新增代碼樣式規(guī)范；
• 17/12/01: 對(duì)資源文件規(guī)范進(jìn)行重構(gòu)；
• 17/11/29: 格式化中英混排；
• 17/03/14: 包名劃分為按功能劃分；
• 17/03/13: 新增其他注釋；
• 17/03/08: 規(guī)范排版，修復(fù) typo 及新增一些規(guī)范；
• 17/03/07: 修訂目錄排版，完善某些細(xì)節(jié)；
• 17/03/06: 發(fā)布初版；