摘要

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

1 前言

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

2 AS 規(guī)范

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

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

3 命名規(guī)范

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

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

3.1 包名

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

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

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

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

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

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

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

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

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

• 很容易刪除功能

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

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

  如果是 PBF，好說，先刪掉對應包，再刪掉功能入口（刪掉包后入口肯定報錯了），完事。

• 高度抽象

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

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

• 只通過 class 來分離邏輯代碼

  PBL 既分離 class 又分離 package，而 PBF 只通過 class 來分離邏輯代碼。

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

  ├── service
          ├── MainService.java
  

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

• package 的大小有意義了

  PBL 中包的大小無限增長是合理的，因為功能越添越多，而 PBF 中包太大（包里 class 太多）表示這塊需要重構（劃分子包）。

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

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é)構，按功能分包具體可以這樣做：

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

3.2 類名

類名都以 UpperCamelCase 風格編寫。

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

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

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

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

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

3.3 方法名

方法名都以 lowerCamelCase 風格編寫。

方法名通常是動詞或動詞短語。

3.4 常量名

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

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

// 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 風格的基礎上改造為如下風格：基本結(jié)構為 scope{Type0}VariableName{Type1}、type0VariableName{Type1}、variableName{Type1}。

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

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

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 個字符前綴來表示作用范圍，1 個字符的前綴必須小寫，前綴后面是由表意性強的一個單詞或多個單詞組成的名字，而且每個單詞的首寫字母大寫，其它字母小寫，這樣保證了對變量名能夠進行正確的斷句。

3.5.2 Type0（控件類型）

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

例如：mIvAvatar、rvBooks、flContainer。

3.5.3 VariableName（變量名）

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

例如：mFirstBook、mPreBook、curBook。

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

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

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

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

例如：mIvAvatarList、userArr、firstNameSet。

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

3.6 參數(shù)名

參數(shù)名以 lowerCamelCase 風格編寫，參數(shù)應該避免用單個字符命名。

3.7 局部變量名

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

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

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

3.8 臨時變量

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

3.9 類型變量名

類型變量可用以下兩種風格之一進行命名：

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

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

4 代碼樣式規(guī)范

4.1 使用標準大括號樣式

左大括號不單獨占一行，與其前面的代碼位于同一行：

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

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

if (condition) {
    body();
}

同樣也接受以下樣式：

if (condition) body();

但不接受以下樣式：

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

4.2 編寫簡短方法

在可行的情況下，盡量編寫短小精煉的方法。我們了解，有些情況下較長的方法是恰當?shù)?，因此對方法的代碼長度沒有做出硬性限制。如果某個方法的代碼超出 40 行，請考慮是否可以在不破壞程序結(jié)構的前提下對其拆解。

4.3 類成員的順序

這并沒有唯一的正確解決方案，但如果都使用一致的順序?qū)岣叽a的可讀性，推薦使用如下排序：

1. 常量
2. 字段
3. 構造函數(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ù)按照他們的生命周期進行排序是一個非常好的習慣，例如，Activity 實現(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 作為其第一個參數(shù)。

正相反，我們把回調(diào)接口應該作為其最后一個參數(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 中的很多類都用到了鍵值對函數(shù)，比如SharedPreferences、Bundle、Intent，所以，即便是一個小應用，我們最終也不得不編寫大量的字符串常量。

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

說明：雖然 Fragment.getArguments() 得到的也是 Bundle ，但因為這是 Bundle 的常用用法，所以特意為此定義一個不同的前綴。

例如：

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

// 與意圖相關的項使用完整的包名作為值的前綴
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 的傳參

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

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

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

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

同理，啟動相關 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 的鍵應該是 private 的，因為它們不再需要暴露給其他類來使用。

4.7 行長限制

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

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

不過存在以下例外情況：

• 如果備注行包含長度超過 100 個字符的示例命令或文字網(wǎng)址，那么為了便于剪切和粘貼，該行可以超過 100 個字符。
• 導入語句行可以超出此限制，因為用戶很少會看到它們（這也簡化了工具編寫流程）。

4.7.1 換行策略

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

4.7.1.1 操作符的換行

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

int longName = anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne
        + theFinalOne;

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

int longName =
        anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne + theFinalOne;

4.7.1.2 函數(shù)鏈的換行

當同一行中調(diào)用多個函數(shù)時（比如使用構建器時），對每個函數(shù)的調(diào)用應該在新的一行中，我們把換行符插入在 . 之前。

例如：

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

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

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

4.7.1.3 多參數(shù)的換行

當一個方法有很多參數(shù)或者參數(shù)很長的時候，我們應該在每個 , 后面進行換行。

比如：

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

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

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

4.7.1.4 RxJava 鏈式的換行

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

例如：

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ī)范

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

如果想對資源文件進行分包可以參考我這篇文章：Android Studio 下對資源進行分包。

5.1 動畫資源文件（anim/ 和 animator/）

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

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

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

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

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

例如：

5.2 顏色資源文件（color/）

專門存放顏色相關的資源文件。

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

例如：sel_btn_font.xml。

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

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

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

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

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

例如：

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

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

5.4 布局資源文件（layout/）

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

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

例如：

5.5 菜單資源文件（menu/）

菜單相關的資源文件應放在該目錄下。

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

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

例如：main_drawer.xml、navigation.xml。

5.6 values 資源文件（values/）

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

5.6.1 colors.xml

<color> 的 name 命名使用下劃線命名法，在你的 colors.xml 文件中應該只是映射顏色的名稱一個 ARGB 值，而沒有其它的。不要使用它為不同的按鈕來定義 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>

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

相反，應該這樣做：

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

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

注意：如果某些顏色和主題有關，那就單獨寫一個 colors_theme.xml。

5.6.2 dimens.xml

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

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

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

5.6.3 strings.xml

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

5.6.4 styles.xml

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

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

應用到 TextView 中：

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

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

5.7 id 命名

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

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

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

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

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

如果是開發(fā)多個系統(tǒng)級別的應用，當多個應用同時用到相同的 so 庫時，一定要確保 so 庫的版本一致，否則可能會引發(fā)應用崩潰。

7 第三方庫規(guī)范

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

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

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

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

8 注釋規(guī)范

為了減少他人閱讀你代碼的痛苦值，請在關鍵地方做好注釋。

8.1 類注釋

每個類完成后應該有作者姓名和聯(lián)系方式的注釋，對自己的代碼負責。

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

具體可以在 AS 中自己配制，進入 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>
 */

這樣便可在每次新建類的時候自動加上該頭注釋。

8.2 方法注釋

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

/**
 * bitmap 轉(zhuǎn) byteArr
 *
 * @param bitmap bitmap 對象
 * @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 塊注釋

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

/*
 * This is
 * okay.
 */

// And so
// is this.

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

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

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

8.4 其他一些注釋

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

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

9 測試規(guī)范

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

9.1 單元測試

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

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

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

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

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

9.2 Espresso 測試

每個 Espresso 測試通常是針對 Activity，所以其測試名就是其被測的 Activity 的名稱加 Test，比如 SignInActivityTest。

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

1. 合理布局，有效運用 <merge>、<ViewStub>、<include> 標簽；

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

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

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

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

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

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

8. 提取方法，去除重復代碼。對于必要的工具類抽取也很重要，這在以后的項目中是可以重用的。

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

10. 項目引入 RxAndroid 響應式編程，可以極大的減少邏輯代碼；

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

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

13. 及時關閉流；

14. 盡量減少對變量的重復計算；

    如下面的操作：

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

    建議替換為：

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

15. 盡量采用懶加載的策略，即在需要的時候才創(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…，應該把其放在最外層；

17. 使用帶緩沖的輸入輸出流進行 IO 操作；

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

19. 盡量在合適的場合使用單例；

    使用單例可以減輕加載的負擔、縮短加載的時間、提高加載的效率，但并不是所有地方都適用于單例，簡單來說，單例主要適用于以下三個方面：

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

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

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

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

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

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

最后啰嗦幾句：

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

附錄

UI 控件縮寫表

常見的英文單詞縮寫表

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

參考

Android 包命名規(guī)范

Android 開發(fā)最佳實踐

Android 編碼規(guī)范

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

Project and code style guidelines

Google Java 編程風格指南

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

版本日志

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