title: Android開發規范

摘要

• 1 前言
• 2 命名規范
• 3 資源文件規范
• 4 版本統一規范
• 5 第三方庫規范
• 6 注釋規范
• 7 其他的一些規范

1 前言

為了利于項目維護以及規范開發，促進成員之間Code Review的效率，故提出以下開發規范

2 命名規范

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

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

2.1 包名

包名全部小寫，連續的單詞只是簡單地連接起來，不使用下劃線。

采用反域名命名規則，全部使用小寫字母。一級包名是頂級域名，通常為com,edu,gov,net,org等，二級包名為公司名，三級包名根據應用進行命名，四級包名為模塊名或層級名。

注意：如果項目采用MVP，所有M、V、P抽取出來的接口都放置在相應模塊的i包下，所有的實現都放置在相應模塊的impl下

2.2 類名

類名都以UpperCamelCase風格編寫。

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

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

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

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

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

2.3 方法名

方法名都以lowerCamelCase風格編寫。

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

2.4 常量名

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

每個常量都是一個靜態final字段，但不是所有靜態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"};

2.5 非常量字段名

非常量字段名以lowerCamelCase風格的基礎上改造為如下風格：基本結構為scopeVariableNameType。

scope：范圍

非公有，非靜態字段命名以m開頭。

靜態字段命名以s開頭。

公有非靜態字段命名以p開頭。

公有靜態字段（全局變量）命名以g開頭。

例子：

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

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

Type：類型

考慮到Android中使用很多UI控件，為避免控件和普通成員變量混淆以及更好達意，所有用來表示控件的成員變量統一加上控件縮寫作為后綴（文末附有縮寫表）。

對于普通變量一般不添加類型后綴，如果統一添加類型后綴，請參考文末的縮寫表。

用統一的量詞通過在結尾處放置一個量詞，就可創建更加統一的變量，它們更容易理解，也更容易搜索。

注意：如果項目中使用ButterKnife，則不添加m前綴，以lowerCamelCase風格命名。

例如，請使用mCustomerStrFirst和mCustomerStrLast，而不要使用mFirstCustomerStr和mLastCustomerStr。

說明：

集合添加如下后綴：List、Map、Set
數組添加如下后綴：Arr

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

2.6 參數名

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

2.7 局部變量名

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

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

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

2.8 臨時變量

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

2.9 類型變量名

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

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

更多還可參考～[阿里巴巴Java開發手冊][阿里巴巴Java開發手冊]

3 資源文件規范

3.1 資源布局文件（XML文件（layout布局文件））

全部小寫，采用下劃線命名法

3.1.1 contentView命名

必須以全部單詞小寫，單詞間以下劃線分割，使用名詞或名詞詞組。

所有Activity或Fragment的contentView必須與其類名對應，對應規則為：將所有字母都轉為小寫，將類型和功能調換（也就是后綴變前綴）。

例如：activity_main.xml

3.1.2 Dialog命名

規則：dialog_描述.xml

例如：dialog_hint.xml

3.1.3 PopupWindow命名

規則：ppw_描述.xml

例如：ppw_info.xml

3.1.4 列表項命名

規則：item_描述.xml

例如：item_city.xml

3.1.5 包含項命名

規則：模塊_(位置)描述.xml

例如：activity_main_head.xml、activity_main_bottom.xml

注意：通用的包含項命名采用：項目名稱縮寫_描述.xml

例如：xxxx_title.xml

3.2 資源文件（圖片drawable文件夾下）

全部小寫，采用下劃線命名法，加前綴區分

命名模式：可加后綴 _small 表示小圖， _big 表示大圖，邏輯名稱可由多個單詞加下劃線組成，采用以下規則：

• 用途_模塊名_邏輯名稱
• 用途_模塊名_顏色
• 用途_邏輯名稱
• 用途_顏色

說明：用途也指控件類型（具體見附錄UI控件縮寫表）

例如：

如果有多種形態，如按鈕選擇器：btn_xx.xml(selector)

注意：使用AndroidStudio的插件SelectorChapek可以快速生成selector，前提是命名要規范。

3.3 動畫文件（anim文件夾下）

全部小寫，采用下劃線命名法，加前綴區分。

具體動畫采用以下規則：模塊名_邏輯名稱。

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

普通的tween動畫采用如下表格中的命名方式：動畫類型_方向

3.4 values中name命名

3.4.1 colors.xml

colors的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值，這使如果需要改變基本色變的很復雜。同時，這些定義是跟一些環境關聯起來的，如button或者comment, 應該放到一個按鈕風格中，而不是在color.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>

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

3.4.2 dimens.xml

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

<resources>

    <!-- font sizes -->
    <dimen name="font_larger">22sp</dimen>
    <dimen name="font_large">18sp</dimen>
    <dimen name="font_normal">15sp</dimen>
    <dimen name="font_small">12sp</dimen>

    <!-- typical spacing between two views -->
    <dimen name="spacing_huge">40dp</dimen>
    <dimen name="spacing_large">24dp</dimen>
    <dimen name="spacing_normal">14dp</dimen>
    <dimen name="spacing_small">10dp</dimen>
    <dimen name="spacing_tiny">4dp</dimen>

    <!-- typical sizes of views -->
    <dimen name="button_height_tall">60dp</dimen>
    <dimen name="button_height_normal">40dp</dimen>
    <dimen name="button_height_short">32dp</dimen>

</resources>

布局時在寫margins和paddings時，你應該使用spacing_xxxx尺寸格式來布局，而不是像對待string字符串一樣直接寫值。 這樣寫會非常有感覺，會使組織和改變風格或布局是非常容易。

3.4.3 strings.xml

strings的name命名使用下劃線命名法，采用以下規則：模塊名+邏輯名稱

3.4.4 styles.xml

幾乎每個項目都需要適當的使用style文件，因為對于一個視圖來說有一個重復的外觀是很常見的，將所有的外觀細節屬性（colors、padding、font）放在style文件中。 在應用中對于大多數文本內容，最起碼你應該有一個通用的style文件，例如：

<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:****的屬性放到一個通用的style中。

將一個大的style文件分割成多個文件， 你可以有多個styles.xml 文件。Android SDK支持其它文件，styles這個文件名稱并沒有作用，起作用的是在文件 里xml的<style>標簽。因此你可以有多個style文件styles.xml、style_home.xml、style_item_details.xml、styles_forms.xml。 不同于資源文件路徑需要為系統構建起的有意義，在res/values目錄下的文件可以任意命名。

3.5 layout中的id命名

命名模式為：view縮寫_模塊名_邏輯名，比如btn_main_search
使用AndroidStudio的插件ButterKnife Zelezny，生成注解非常方便，原生的話可以使用Android Code Generator插件。

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

4 版本統一規范

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

具體可以參考我寫的這篇博文～[Android開發之版本統一規范][Android開發之版本統一規范]

5 第三方庫規范

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

個人推薦Team可使用如下優秀輪子：

• [Retrofit][Retrofit]
• [RxAndroid][RxAndroid]
• [OkHttp][OkHttp]
• [Glide][Glide]/[Fresco][Fresco]
• [Gson][Gson]/[Fastjson][Fastjson]
• [EventBus][EventBus]/[AndroidEventBus][AndroidEventBus]
• [GreenDao][GreenDao]

6 注釋規范

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

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

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

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

6.3 塊注釋

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

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

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

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

7 其他的一些規范

1. 合理布局，有效運用<merge>、<ViewStub>、<include>標簽；
2. Activity和Fragment里面有許多重復的操作以及操作步驟，所以我們都需要提供一個BaseActivity和BaseFragment，讓所有的Activity和Fragment都繼承這個基類。
3. 方法基本上都按照調用的先后順序在各自區塊中排列；
4. 相關功能作為小區塊放在一起（或者封裝掉）；
5. 當一個類有多個構造函數，或是多個同名方法，這些函數/方法應該按順序出現在一起，中間不要放進其它函數/方法；
6. 數據提供統一的入口。無論是在 MVP、MVC 還是 MVVM 中，提供一個統一的數據入口，都可以讓代碼變得更加易于維護。比如可使用一個DataManager，把 http、preference、eventpost、database 都放在DataManger里面進行操作，我們只需要與DataManger打交道；
7. 多用組合, 少用繼承；
8. 提取方法, 去除重復代碼。對于必要的工具類抽取也很重要，這在以后的項目中是可以重用的。
9. 可引入 Dagger2 減少模塊之間的耦合性。Dagger2 是一個依賴注入框架，使用代碼自動生成創建依賴關系需要的代碼。減少很多模板化的代碼，更易于測試，降低耦合，創建可復用可互換的模塊；
10. 項目引入RxJava + RxAndroid這些響應式編程，可以極大的減少邏輯代碼；
11. 通過引入事件總線，如：EventBus、AndroidEventBus、RxBus，它允許我們在DataLayer中發送事件，以便ViewLayer中的多個組件都能夠訂閱到這些事件，減少回調；
12. 使用AS自帶的Lint來優化代碼結構（什么，你不會？右鍵module、目錄或者文件，選擇Analyze → Inspect Code）；
13. 最后不要忘了內存泄漏的檢測；

附錄

UI控件縮寫表

常見的英文單詞縮寫表

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

參考

Android 編碼規范
阿里巴巴Java開發手冊
Google Java編程風格指南

個人博客地址