## 摘要 * 1 前言 * 2 AS 規范 * 3 命名規范 * 4 代碼樣式規范 * 5 資源文件規范 * 6 版本統一規范 * 7 注釋規范 * 8 測試規范 * 9 其他的一些規范 ### 1 前言 為了有利于項目維護、增強代碼可讀性、提升 Code Review 效率以及規范團隊安卓開發，故提出以下安卓開發規范 ### 2 AS 規范 工欲善其事，必先利其器。 1. 盡量使用最新的穩定版的 IDE 進行開發； 2. 編碼格式統一為 UTF-8； 3. 編輯完 .java、.xml 等文件后一定要 格式化，格式化，格式化（如果團隊有公共的樣式包，那就遵循它，否則統一使用 AS 默認模板即可）； 4. 刪除多余的 import，減少警告出現，可利用 AS 的 Optimize Imports（Settings -> Keymap -> Optimize Imports）快捷鍵； ### 3 命名規范 代碼中的命名嚴禁使用拼音與英文混合的方式，更不允許直接使用中文的方式。正確的英文拼寫和語法可以讓閱讀者易于理解，避免歧義。 > 注意：即使純拼音命名方式也要避免采用。但 alibaba、taobao、youku、hangzhou 等國際通用的名稱，可視同英文。 #### 3.1 包名 包名全部小寫，連續的單詞只是簡單地連接起來，不使用下劃線，采用反域名命名規則，全部使用小寫字母。一級包名是頂級域名，通常為 com、edu、gov、net、org 等，二級包名為公司名，三級包名根據應用進行命名，后面就是對包名的劃分了，關于包名的劃分，推薦采用 PBF（按功能分包 Package By Feature），一開始我們采用的也是 PBL（按層分包 Package By Layer），很坑爹。PBF 可能不是很好區分在哪個功能中，不過也比 PBL 要好找很多，且 PBF 與 PBL 相比較有如下優勢： * package 內高內聚，package 間低耦合 哪塊要添新功能，只改某一個 package 下的東西。 PBL 降低了代碼耦合，但帶來了 package 耦合，要添新功能，需要改 model、dbHelper、view、service 等等，需要改動好幾個 package 下的代碼，改動的地方越多，越容易產生新問題，不是嗎？ PBF 的話 featureA 相關的所有東西都在 featureA 包，feature 內高內聚、高度模塊化，不同 feature 之間低耦合，相關的東西都放在一起，還好找。 * package 有私有作用域（package-private scope） 你負責開發這塊功能，這個目錄下所有東西都是你的。 PBL 的方式是把所有工具方法都放在 util 包下，小張開發新功能時候發現需要一個 xxUtil，但它又不是通用的，那應該放在哪里？沒辦法，按照分層原則，我們還得放在 util 包下，好像不太合適，但放在其它包更不合適，功能越來越多，util 類也越定義越多。后來小李負責開發一塊功能時發現需要一個 xxUtil，同樣不通用，去 util 包一看，怎么已經有了，而且還沒法復用，只好放棄 xx 這個名字，改為 xxxUtil……，因為 PBL 的 package 沒有私有作用域，每一個包都是 public（跨包方法調用是很平常的事情，每一個包對其它包來說都是可訪問的）；如果是 PBF，小張的 xxUtil 自然放在 featureA 下，小李的 xxUtil 在 featureB 下，如果覺得 util 好像是通用的，就去 util 包看看要不要把工具方法添進 xxUtil, class 命名沖突沒有了。 PBF 的 package 有私有作用域，featureA 不應該訪問 featureB 下的任何東西（如果非訪問不可，那就說明接口定義有問題）。 * 很容易刪除功能 統計發現新功能沒人用，這個版本那塊功能得去掉。 如果是 PBL，得從功能入口到整個業務流程把受到牽連的所有能刪的代碼和 class 都揪出來刪掉，一不小心就完蛋。 如果是 PBF，好說，先刪掉對應包，再刪掉功能入口（刪掉包后入口肯定報錯了），完事。 * 高度抽象 解決問題的一般方法是從抽象到具體，PBF 包名是對功能模塊的抽象，包內的 class 是實現細節，符合從抽象到具體，而 PBL 弄反了。 PBF 從確定 AppName 開始，根據功能模塊劃分 package，再考慮每塊的具體實現細節，而 PBL 從一開始就要考慮要不要 dao 層，要不要 com 層等等。 * 只通過 class 來分離邏輯代碼 PBL 既分離 class 又分離 package，而 PBF 只通過 class 來分離邏輯代碼。 沒有必要通過 package 分離，因為 PBL 中也可能出現尷尬的情況： ├── 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 太多）表示這塊需要重構（劃分子包）。 我們大谷歌也有相應的 Sample：**[todo-mvp](https://link.jianshu.com/?t=https://github.com/googlesamples/android-architecture/tree/todo-mvp/)**，其結構如下所示，很值得學習。 ``` `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 ``` 參考以上的代碼結構，按功能分包具體可以這樣做： com └── domain └── app ├── App.java 定義 Application 類 ├── Config.java 定義配置數據（常量） ├── base 基礎組件 ├── custom\_view 自定義視圖 ├── data 數據處理 │ ├── DataManager.java 數據管理器， │ ├── local 來源于本地的數據，比如 SP，Database，File │ ├── model 定義 model（數據結構以及 getter/setter、compareTo、equals 等等，不含復雜操作） │ └── remote 來源于遠端的數據 ├── feature 功能 │ ├── feature0 功能 0 │ │ ├── feature0Activity.java │ │ ├── feature0Fragment.java │ │ ├── xxAdapter.java │ │ └── ... 其他 class │ └── ...其他功能 ├── injection 依賴注入 ├── util 工具類 └── widget 小部件 #### 3.2 類名 類名都以 UpperCamelCase 風格編寫。 類名通常是名詞或名詞短語，接口名稱有時可能是形容詞或形容詞短語。現在還沒有特定的規則或行之有效的約定來命名注解類型。 名詞，采用大駝峰命名法，盡量避免縮寫，除非該縮寫是眾所周知的， 比如 HTML、URL，如果類名稱中包含單詞縮寫，則單詞縮寫的每個字母均應大寫。  測試類的命名以它要測試的類的名稱開始，以 Test 結束。例如：HashTest 或 HashIntegrationTest。 接口（interface）：命名規則與類一樣采用大駝峰命名法，多以 able 或 ible 結尾，如 interface Runnable、interface Accessible。 > 注意：如果項目采用 MVP，所有 Model、View、Presenter 的接口都以 I 為前綴，不加后綴，其他的接口采用上述命名規則。 #### 3.3 方法名 方法名都以 lowerCamelCase 風格編寫。 方法名通常是動詞或動詞短語。  #### 3.4 常量名 常量名命名模式為 CONSTANT\_CASE，全部字母大寫，用下劃線分隔單詞。那到底什么算是一個常量？ 每個常量都是一個 static final 字段，但不是所有 static final 字段都是常量。在決定一個字段是否是一個常量時，得考慮它是否真的感覺像是一個常量。例如，如果觀測任何一個該實例的狀態是可變的，則它幾乎肯定不會是一個常量。只是永遠不打算改變的對象一般是不夠的，它要真的一直不變才能將它示為常量。 ``` `// 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 風格的基礎上改造為如下風格：基本結構為 scope{Type0}VariableName{Type1}、type0VariableName{Type1}、variableName{Type1}。 說明：{} 中的內容為可選。 > 注意：所有的 VO（值對象）統一采用標準的 lowerCamelCase 風格編寫，所有的 DTO（數據傳輸對象）就按照接口文檔中定義的字段名編寫。 ##### 3.5.1 scope（范圍） 非公有，非靜態字段命名以 m 開頭。 靜態字段命名以 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 控件，為避免控件和普通成員變量混淆以及更好地表達意思，所有用來表示控件的成員變量統一加上控件縮寫作為前綴。 例如：mIvAvatar、rvBooks、flContainer。 ##### 3.5.3 VariableName（變量名） 變量名中可能會出現量詞，我們需要創建統一的量詞，它們更容易理解，也更容易搜索。 例如：mFirstBook、mPreBook、curBook。  ##### 3.5.4 Type1（數據類型） 對于表示集合或者數組的非常量字段名，我們可以添加后綴來增強字段的可讀性，比如： 集合添加如下后綴：List、Map、Set。 數組添加如下后綴：Arr。 例如：mIvAvatarList、userArr、firstNameSet。 > 注意：如果數據類型不確定的話，比如表示的是很多書，那么使用其復數形式來表示也可，例如 mBooks。 #### 3.6 參數名 參數名以 lowerCamelCase 風格編寫，參數應該避免用單個字符命名。 #### 3.7 局部變量名 局部變量名以 lowerCamelCase 風格編寫，比起其它類型的名稱，局部變量名可以有更為寬松的縮寫。 雖然縮寫更寬松，但還是要避免用單字符進行命名，除了臨時變量和循環變量。 即使局部變量是 final 和不可改變的，也不應該把它示為常量，自然也不能用常量的規則去命名它。 #### 3.8 臨時變量 臨時變量通常被取名為 i、j、k、m 和 n，它們一般用于整型；c、d、e，它們一般用于字符型。 如：for (int i = 0; i < len; i++)。 #### 3.9 類型變量名 類型變量可用以下兩種風格之一進行命名： 1. 單個的大寫字母，后面可以跟一個數字（如：E, T, X, T2）。 2. 以類命名方式（參考3.2 類名），后面加個大寫的 T（如：RequestT, FooBarT）。 更多還可參考：**[阿里巴巴 Java 開發手冊](https://link.jianshu.com/?t=https://github.com/alibaba/p3c/blob/master/%E9%98%BF%E9%87%8C%E5%B7%B4%E5%B7%B4Java%E5%BC%80%E5%8F%91%E6%89%8B%E5%86%8C%EF%BC%88%E7%BA%AA%E5%BF%B5%E7%89%88%EF%BC%89.pdf)** ### 4 代碼樣式規范 #### 4.1 使用標準大括號樣式 左大括號不單獨占一行，與其前面的代碼位于同一行： ``` class MyClass { int func() { if (something) { // ... } else if (somethingElse) { // ... } else { // ... } } } ``` 我們需要在條件語句周圍添加大括號。例外情況：如果整個條件語句（條件和主體）適合放在同一行，那么您可以（但不是必須）將其全部放在一行上。例如，我們接受以下樣式： ``` if (condition) { body(); } ``` 同樣也接受以下樣式： ``` if (condition) body(); ``` 但不接受以下樣式： ``` if (condition) body(); // bad! ``` #### 4.2 編寫簡短方法 在可行的情況下，盡量編寫短小精煉的方法。我們了解，有些情況下較長的方法是恰當的，因此對方法的代碼長度沒有做出硬性限制。如果某個方法的代碼超出 40 行，請考慮是否可以在不破壞程序結構的前提下對其拆解。 #### 4.3 類成員的順序 這并沒有唯一的正確解決方案，但如果都使用一致的順序將會提高代碼的可讀性，推薦使用如下排序： 1. 常量 2. 字段 3. 構造函數 4. 重寫函數和回調 5. 公有函數 6. 私有函數 7. 內部類或接口 例如： ``` 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），那么把重寫函數按照他們的生命周期進行排序是一個非常好的習慣，例如，Activity 實現了 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 函數參數的排序 在 Android 開發過程中，Context 在函數參數中是再常見不過的了，我們最好把 Context 作為其第一個參數。 正相反，我們把回調接口應該作為其最后一個參數。 例如： ``` `// 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 中的很多類都用到了鍵值對函數，比如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 傳遞數據通過 Intent 或 Bundle 時，不同值的鍵須遵循上一條所提及到的。 當 Activity 或 Fragment 啟動需要傳遞參數時，那么它需要提供一個 public static 的函數來幫助啟動或創建它。 這方面，AS 已幫你寫好了相關的 Live Templates，啟動相關 Activity 的只需要在其內部輸入 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 在其內部輸入 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; } ``` > 注意：這些函數需要放在 onCreate() 之前的類的頂部；如果我們使用了這種方式，那么 extras 和 arguments 的鍵應該是 private 的，因為它們不再需要暴露給其他類來使用。 #### 4.7 行長限制 代碼中每一行文本的長度都應該不超過 100 個字符。雖然關于此規則存在很多爭論，但最終決定仍是以 100 個字符為上限，如果行長超過了 100（AS 窗口右側的豎線就是設置的行寬末尾 ），我們通常有兩種方法來縮減行長。 * 提取一個局部變量或方法（最好）。 * 使用換行符將一行換成多行。 不過存在以下例外情況： * 如果備注行包含長度超過 100 個字符的示例命令或文字網址，那么為了便于剪切和粘貼，該行可以超過 100 個字符。 * 導入語句行可以超出此限制，因為用戶很少會看到它們（這也簡化了工具編寫流程）。 ##### 4.7.1 換行策略 這沒有一個準確的解決方案來決定如何換行，通常不同的解決方案都是有效的，但是有一些規則可以應用于常見的情況。 ##### 4.7.1.1 操作符的換行 除賦值操作符之外，我們把換行符放在操作符之前，例如： ``` int longName = anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne \+ theFinalOne; ``` 賦值操作符的換行我們放在其后，例如： ``` int longName = anotherVeryLongVariable + anEvenLongerOne - thisRidiculousLongOne + theFinalOne; ``` ##### 4.7.1.2 函數鏈的換行 當同一行中調用多個函數時（比如使用構建器時），對每個函數的調用應該在新的一行中，我們把換行符插入在 . 之前。 例如： ``` Picasso.with(context).load("https://blankj.com/images/avatar.jpg").into(ivAvatar); ``` 我們應該使用如下規則： ``` Picasso.with(context) .load("https://blankj.com/images/avatar.jpg") .into(ivAvatar); ``` ##### 4.7.1.3 多參數的換行 當一個方法有很多參數或者參數很長的時候，我們應該在每個 , 后面進行換行。 比如： ``` loadPicture(context, "https://blankj.com/images/avatar.jpg", ivAvatar, "Avatar of the user", clickListener); ``` 我們應該使用如下規則： ``` loadPicture(context, "https://blankj.com/images/avatar.jpg", ivAvatar, "Avatar of the user", clickListener); ``` ##### 4.7.1.4 RxJava 鏈式的換行 RxJava 的每個操作符都需要換新行，并且把換行符插入在 . 之前。 例如： ``` public Observable syncLocations() { return mDatabaseHelper.getAllLocations() .concatMap(new Func1>() { @Override public Observable call(Location location) { return mRetrofitService.getLocation(location.id); } }) .retry(new Func2() { @Override public Boolean call(Integer numRetries, Throwable throwable) { return throwable instanceof RetrofitError; } }); } ``` ### 5 資源文件規范 資源文件命名為全部小寫，采用下劃線命名法。 #### 5.1 動畫資源文件（anim/ 和 animator/） 安卓主要包含屬性動畫和視圖動畫，其視圖動畫包括補間動畫和逐幀動畫。屬性動畫文件需要放在 res/animator/ 目錄下，視圖動畫文件需放在 res/anim/ 目錄下。 命名規則：{模塊名\_}邏輯名稱。 說明：{} 中的內容為可選，邏輯名稱 可由多個單詞加下劃線組成。 例如：refresh\_progress.xml、market\_cart\_add.xml、market\_cart\_remove.xml。 如果是普通的補間動畫或者屬性動畫，可采用：動畫類型\_方向 的命名方式。 例如：  #### 5.2 顏色資源文件（color/） 專門存放顏色相關的資源文件。 命名規則：類型\_邏輯名稱。 例如：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/ 目錄下。 命名規則：類型{\_模塊名}\_邏輯名稱、類型{\_模塊名}\_顏色。 說明：{} 中的內容為可選；類型 可以是 可繪制對象資源類型，也可以是控件類型（具體見附錄[UI 控件縮寫表]；最后可加后綴 \_small 表示小圖，\_big 表示大圖。 例如：  如果有多種形態，如按鈕選擇器：sel\_btn\_xx.xml，采用如下命名：  > 注意：使用 Android Studio 的插件 SelectorChapek 可以快速生成 selector，前提是命名要規范。 #### 5.4 布局資源文件（layout/） 命名規則：類型\_模塊名、類型{\_模塊名}\_邏輯名稱。 說明：{} 中的內容為可選。 例如：  #### 5.5 菜單資源文件（menu/） 菜單相關的資源文件應放在該目錄下。 命名規則：{模塊名\_}邏輯名稱 說明：{} 中的內容為可選。 例如：main\_drawer.xml、navigation.xml。 #### 5.6 values 資源文件（values/） values/ 資源文件下的文件都以 s 結尾，如 attrs.xml、colors.xml、dimens.xml，起作用的不是文件名稱，而是 標簽下的各種標簽，比如 決定樣式， 決定顏色，所以，可以把一個大的 xml 文件分割成多個小的文件，比如可以有多個 style 文件，如 styles.xml、styles\_home.xml、styles\_item\_details.xml、styles\_forms.xml。 ##### 5.6.1 colors.xml 的 name 命名使用下劃線命名法，在你的 colors.xml 文件中應該只是映射顏色的名稱一個 ARGB 值，而沒有其它的。不要使用它為不同的按鈕來定義 ARGB 值。 例如，不要像下面這樣做： #FFFFFF #2A91BD #5F5F5F #939393 #FFFFFF #FF9D2F ... #323232 使用這種格式，會非常容易重復定義 ARGB 值，而且如果應用要改變基色的話會非常困難。同時，這些定義是跟一些環境關聯起來的，如 button 或者 comment，應該放到一個按鈕風格中，而不是在 colors.xml 文件中。 相反，應該這樣做： #FFFFFF #DBDBDB #939393 #5F5F5F #323232 #27D34D #2A91BD #FF9D2F #FF432F 向應用設計者那里要這個調色板，名稱不需要跟 "green"、"blue" 等等相同。"brand\_primary"、"brand\_secondary"、"brand\_negative" 這樣的名字也是完全可以接受的。像這樣規范的顏色很容易修改或重構，會使應用一共使用了多少種不同的顏色變得非常清晰。通常一個具有審美價值的 UI 來說，減少使用顏色的種類是非常重要的。 > 注意：如果某些顏色和主題有關，那就單獨寫一個 colors\_theme.xml。 ##### 5.6.2 dimens.xml 像對待 colors.xml 一樣對待 dimens.xml 文件，與定義顏色調色板一樣，你同時也應該定義一個空隙間隔和字體大小的“調色板”。 一個好的例子，如下所示： `<resources>` 22sp 18sp 15sp 12sp 40dp 24dp 14dp 10dp 4dp 60dp 40dp 32dp `</resources>` 布局時在寫 margins 和 paddings 時，你應該使用 spacing\_xx 尺寸格式來布局，而不是像對待 string 字符串一樣直接寫值，像這樣規范的尺寸很容易修改或重構，會使應用所有用到的尺寸一目了然。 這樣寫會非常有感覺，會使組織和改變風格或布局非常容易。 ##### 5.6.3 strings.xml 的 name 命名使用下劃線命名法，采用以下規則：{模塊名\_}邏輯名稱，這樣方便同一個界面的所有 string 都放到一起，方便查找。  ##### 5.6.4 styles.xml 的 name 命名使用大駝峰命名法，幾乎每個項目都需要適當的使用 styles.xml 文件，因為對于一個視圖來說，有一個重復的外觀是很常見的，將所有的外觀細節屬性（colors、padding、font）放在 styles.xml 文件中。 在應用中對于大多數文本內容，最起碼你應該有一個通用的 styles.xml 文件，例如： @dimen/font\_normal @color/basic\_black `</style>` 應用到 TextView 中： ``` `<TextView` `android:layout_width="wrap_content"` `android:layout_height="wrap_content"` `android:text="@string/price"` `style="@style/ContentText"` `/>` ``` 或許你需要為按鈕控件做同樣的事情，不要停止在那里，將一組相關的和重復 android:xxxx 的屬性放到一個通用的 中。 #### 5.7 id 命名 命名規則：view縮寫{\_模塊名}\_邏輯名，例如： btn\_main\_search、btn\_back。 如果在項目中有用黃油刀的話，使用 AS 的插件：ButterKnife Zelezny，可以非常方便幫助你生成注解；沒用黃油刀的話可以使用 Android Code Generator 插件。 ### 6 版本統一規范 Android 開發存在著眾多版本的不同，比如 compileSdkVersion、minSdkVersion、targetSdkVersion 以及項目中依賴第三方庫的版本，不同的 module 及不同的開發人員都有不同的版本，所以需要一個統一版本規范的文件。 如果是開發多個系統級別的應用，當多個應用同時用到相同的 so 庫時，一定要確保 so 庫的版本一致，否則可能會引發應用崩潰。 ### 7 注釋規范 為了減少他人閱讀你代碼的痛苦值，請在關鍵地方做好注釋。 #### 7.1 類注釋 每個類完成后應該有作者姓名和聯系方式的注釋，對自己的代碼負責。 ``` `/**` `* <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>` `*/` ``` 這樣便可在每次新建類的時候自動加上該頭注釋。 #### 7.2 方法注釋 每一個成員方法（包括自定義成員方法、覆蓋方法、屬性方法）的方法頭都必須做方法頭注釋，在方法前一行輸入 /\*\* + 回車 或者設置 Fix doc comment（Settings -> Keymap -> Fix doc comment）快捷鍵，AS 便會幫你生成模板，我們只需要補全參數即可，如下所示。 ``` `/**` `* bitmap 轉 byteArr` `*` \* @param bitmap bitmap 對象 \* @param format 格式 \* @return 字節數組 `*/` 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(); } ``` #### 7.3 塊注釋 塊注釋與其周圍的代碼在同一縮進級別。它們可以是 /\* ... \*/ 風格，也可以是 // ... 風格（//后最好帶一個空格）。對于多行的 /\* ... \*/ 注釋，后續行必須從 \* 開始， 并且與前一行的 \* 對齊。以下示例注釋都是 OK 的。 ``` `/*` `* This is` `* okay.` `*/` `// And so` `// is this.` `/* Or you can` `* even do this. */` ``` 注釋不要封閉在由星號或其它字符繪制的框架里。 > Tip：在寫多行注釋時，如果你希望在必要時能重新換行（即注釋像段落風格一樣），那么使用 /\* ... \*/。 #### 7.4 其他一些注釋 AS 已幫你集成了一些注釋模板，我們只需要直接使用即可，在代碼中輸入 todo、fixme 等這些注釋模板，回車后便會出現如下注釋。 ``` // TODO: 17/3/14 需要實現，但目前還未實現的功能的說明 // FIXME: 17/3/14 需要修正，甚至代碼是錯誤的，不能工作，需要修復的說明 ``` ### 8 測試規范 業務開發完成之后，開發人員做單元測試，單元測試完成之后，保證單元測試全部通過，同時單元測試代碼覆蓋率達到一定程度（這個需要開發和測試約定，理論上越高越好），開發提測。 #### 8.1 單元測試 測試類的名稱應該是所測試類的名稱加 Test，我們創建 DatabaseHelper 的測試類，其名應該叫 DatabaseHelperTest。 測試函數被 @Test 所注解，函數名通常以被測試的方法為前綴，然后跟隨是前提條件和預期的結果。 * 模板：void methodName前提條件和預期結果() * 例子：void signInWithEmptyEmailFails() > 注意：如果函數足夠清晰，那么前提條件和預期的結果是可以省略的。 有時一個類可能包含大量的方法，同時需要對每個方法進行幾次測試。在這種情況下，建議將測試類分成多個類。例如，如果 DataManager 包含很多方法，我們可能要把它分成 DataManagerSignInTest、DataManagerLoadUsersTest 等等。 #### 8.2 Espresso 測試 每個 Espresso 測試通常是針對 Activity，所以其測試名就是其被測的 Activity 的名稱加 Test，比如 SignInActivityTest。 ### 9 其他的一些規范 1. 合理布局，有效運用 、、 標簽； 2. Activity 和 Fragment 里面有許多重復的操作以及操作步驟，所以我們都需要提供一個 BaseActivity 和 BaseFragment，讓所有的 Activity 和 Fragment 都繼承這個基類。 3. 方法基本上都按照調用的先后順序在各自區塊中排列； 4. 相關功能作為小區塊放在一起（或者封裝掉）； 5. 當一個類有多個構造函數，或是多個同名函數，這些函數應該按順序出現在一起，中間不要放進其它函數； 6. 數據提供統一的入口。無論是在 MVP、MVC 還是 MVVM 中，提供一個統一的數據入口，都可以讓代碼變得更加易于維護。比如可使用一個 DataManager，把 http、preference、eventpost、database 都放在 DataManager 里面進行操作，我們只需要與 DataManager打交道； 7. 多用組合，少用繼承； 8. 提取方法，去除重復代碼。對于必要的工具類抽取也很重要，這在以后的項目中是可以重用的。 9. 可引入 Dagger2 減少模塊之間的耦合性。Dagger2 是一個依賴注入框架，使用代碼自動生成創建依賴關系需要的代碼。減少很多模板化的代碼，更易于測試，降低耦合，創建可復用可互換的模塊； 10. 項目引入 RxAndroid 響應式編程，可以極大的減少邏輯代碼； 11. 通過引入事件總線，如：EventBus、AndroidEventBus、RxBus，它允許我們在 DataLayer 中發送事件，以便 ViewLayer 中的多個組件都能夠訂閱到這些事件，減少回調； 12. 盡可能使用局部變量； 13. 及時關閉流； 14. 盡量減少對變量的重復計算； 如下面的操作： ``` for (int i = 0; i < list.size(); i++) { ... } ``` 建議替換為： ``` for (int i = 0, len = list.size(); i < len; i++) { ... } ``` 15. 盡量采用懶加載的策略，即在需要的時候才創建； 例如： String str = "aaa"; if (i == 1) { list.add(str); } 建議替換為： if (i == 1) { String str = "aaa"; list.add(str); } 16. 不要在循環中使用 try…catch…，應該把其放在最外層； 17. 使用帶緩沖的輸入輸出流進行 IO 操作； 18. 盡量使用 HashMap、ArrayList、StringBuilder，除非線程安全需要，否則不推薦使用 HashTable、Vector、StringBuffer，后三者由于使用同步機制而導致了性能開銷； 19. 盡量在合適的場合使用單例； 使用單例可以減輕加載的負擔、縮短加載的時間、提高加載的效率，但并不是所有地方都適用于單例，簡單來說，單例主要適用于以下三個方面： 1. 控制資源的使用，通過線程同步來控制資源的并發訪問。 2. 控制實例的產生，以達到節約資源的目的。 3. 控制數據的共享，在不建立直接關聯的條件下，讓多個不相關的進程或線程之間實現通信。 21. 把一個基本數據類型轉為字符串，基本數據類型.toString() 是最快的方式，String.valueOf(數據) 次之，數據 + "" 最慢； 22. 使用 AS 自帶的 Lint 來優化代碼結構（什么，你不會？右鍵 module、目錄或者文件，選擇 Analyze -> Inspect Code）； 23. 最后不要忘了內存泄漏的檢測； * * * 最后啰嗦幾句： * 好的命名規則能夠提高代碼質量，使得新人加入項目的時候降低理解代碼的難度； * 規矩終究是死的，適合團隊的才是最好的； * 命名規范需要團隊一起齊心協力來維護執行，在團隊生活里，誰都不可能獨善其身； * 一開始可能會有些不習慣，持之以恒，總會成功的。 ## 附錄 ### UI 控件縮寫表 | 名稱 | 縮寫 | | --- | --- | |Button | btn| |CheckBox|cb| |EditText|et| |FrameLayout|fl| |GridView|gv| |ImageButton|ib| |ImageView|iv| | LinearLayout| ll| | ListView| lv| | ProgressBar| pb| | RadioButtion| rb| | RecyclerView| rv| | RelativeLayout| rl| | ScrollView| sv| | SeekBar| sb| | Spinners| pn| | TextView| tv| | ToggleButton| tb| | VideoView| vv| | WebView| wv|