Android技術積累:開發規範

原文鏈接：http://keeganlee.me/post/android/20150709

上個月發佈了Android項目重構的三篇系列文章，其中，界面篇中提到了在項目中保持規範性的重要性，也有簡單舉了幾個例子。這篇文章則將其延伸，提供更完整的開發規範說明。

書寫規範

1. 編碼方式統一用UTF-8. Android Studio默認已是UTF-8，只要不去改動它就可以了。

2. 縮進統一爲4個空格，將Tab size設置爲4則可以保證tab鍵按4個空格縮進。另外，不要勾選上Use tab character，可以保證切換到不同tab長度的環境時還能繼續保持統一的4個空格的縮進樣式。

3. 花括號不要單獨一行，和它前面的代碼同一行。而且，花括號與前面的代碼之間用一個空格隔開。

public void method() { // Good 

} 

public void method()
{ // Bad
}  

public void method(){ // Bad

} 

4. 空格的使用

if、else、for、switch、while等邏輯關鍵字與後面的語句留一個空格隔開。

// Good
if (booleanVariable) {
    // TODO while booleanVariable is true
} else {
    // TODO else
}

// Bad
if(booleanVariable) {
    // TODO while booleanVariable is true
}else {
    // TODO else
}

運算符兩邊各用一個空格隔開。

int result = a + b; //Good, = 和 + 兩邊各用一個空格隔開
int result=a+b; //Bad,=和+兩邊沒用空格隔開

方法的每個參數之間用一個空格隔開。

public void method(String param1, String param2); // Good，param1後面的逗號與String之間隔了一個空格
method(param1, param2); // Good，方法調用時，param1後面的逗號與param2之間隔了一個空格
method(param1,param2); // Bad，沒有用一個空格隔開

5. 空行的使用

將邏輯相關的代碼段用空行隔開，以提高可讀性。空行也只空一行，不要空多行。在以下情況需用一個空行：

• 兩個方法之間
• 方法內的兩個邏輯段之間
• 方法內的局部變量和方法的第一條邏輯語句之間
• 常量和變量之間

6. 當一個表達式無法容納在一行內時，可換行顯示，另起的新行用8個空格縮進。

someMethod(longExpression1, longExpression2, longExpression3,  
        longExpression4, longExpression5);

7. 一行聲明一個變量，不要一行聲明多個變量，這樣有利於寫註釋。

private String param1; // 參數1
private String param2; // 參數2

8. 行寬設置爲100，設置格式化時自動斷行到行寬位置。

9. 使用快捷鍵進行代碼自動格式化。

Windows：CTRL+ALT+L
Mac：OPTION+COMMAND+L

10. 一個方法最多不要超過40行代碼。

11. 範圍型的常量用枚舉類定義，而不要直接用整型或字符，這樣可以減少範圍值的有效性檢查。

// 用枚舉類定義，Good
public enum CouponType {
    // 現金券
    @SerializedName("1")
    CASH,

    // 抵用券
    @SerializedName("2")
    DEBIT,

    // 折扣券
    @SerializedName("3")
    DISCOUNT
}

// 用整型定義，Bad
public static final int TYPE_CASH = 1; // 現金券
public static final int TYPE_DEBIT = 2; // 抵扣券
public static final int TYPE_DISCOUNT = 3; // 折扣券

12. 文字大小的單位統一用sp，元素大小的單位統一用dp。

13. 應用中的字符串統一在strings.xml中定義，然後在代碼和佈局文件中引用。

14. 顏色值統一在colors.xml中定義，然後在代碼和佈局文件中引用。另外，不要在代碼和佈局文件中引用系統的顏色，除了透明。

命名規範

1. 包命名

域名反寫+項目名稱+模塊名稱，全部單詞用小寫字母。
例如，我的KAndroid項目的Model模塊包名如下：

me.keeganlee.kandroid.model

2. 類和接口命名

使用大駝峯規則，用名詞或名詞詞組命名，每個單詞的首字母大寫。
以下爲幾種常用類的命名：

• activity類，命名以Activity爲後綴，如：LoginActivity
• fragment類，命名以Fragment爲後綴，如：ShareDialogFragment
• service類，命名以Service爲後綴，如：DownloadService
• adapter類，命名以Adapter爲後綴，如：CouponListAdapter
• 工具類，命名以Util爲後綴，如：EncryptUtil
• 模型類，命名以BO爲後綴，如：CouponBO
• 接口實現類，命名以Impl爲後綴，如：ApiImpl

3. 方法命名

使用小駝峯規則，用動詞命名，第一個單詞的首字母小寫，其他單詞的首字母大寫。
以下爲幾種常用方法的命名：

• 初始化方法，命名以init開頭，例：initView
• 按鈕點擊方法，命名以to開頭，例：toLogin
• 設置方法，命名以set開頭，例：setData
• 具有返回值的獲取方法，命名以get開頭，例：getData
• 通過異步加載數據的方法，命名以load開頭，例：loadData
• 布爾型的判斷方法，命名以is或has，或具有邏輯意義的單詞如equals，例：isEmpty

4. 控件縮寫

控件	縮寫	控件	縮寫
TextView	txt	EditText	edt
Button	btn	ImageButton	ibtn
ImageView	img	ListView	list
RadioGroup	group	RadioButton	rbtn
ProgressBar	progress	SeekBar	seek
CheckBox	chk	Spinner	spinner
TableLayout	table	TableRow	row
LinearLayout	llayout	RelativeLayout	rlayout
ScrollView	scroll	SearchView	search
TabHost	host	TabWidget	widget

5. 常量命名

全部爲大寫單詞，單詞之間用下劃線分開。

public final static int PAGE_SIZE = 20;

6. 變量命名

{範圍描述+}意義描述+類型描述的組合，用駝峯式，首字母小寫。

private TextView headerTitleTxt; // 標題欄的標題
private Button loginBtn; // 登錄按鈕
private CouponBO couponBO; // 券實例

7. 控件id命名

控件縮寫_{範圍_}意義，範圍可選，只在有明確定義的範圍內才需要加上。

<!-- 這是標題欄的標題 -->
<TextView
    android:id="@+id/txt_header_title"
    ... />

<!-- 這是登錄按鈕 -->
<Button
    android:id="@+id/btn_login"
    ... />

8. layout命名

組件類型_{範圍_}功能，範圍可選，只在有明確定義的範圍內才需要加上。
以下爲幾種常用的組件類型命名：

• activity_{範圍_}功能，爲Activity的命名格式
• fragment_{範圍_}功能，爲Fragment的命名格式
• dialog_{範圍_}功能，爲Dialog的命名格式
• item_list_{範圍_}功能，爲ListView的item命名格式
• item_grid_{範圍_}功能，爲GridView的item命名格式
• header_list_{範圍_}功能，爲ListView的HeaderView命名格式
• footer_list_{範圍_}功能，爲ListView的FooterView命名格式

9. strings的命名

類型_{範圍_}功能，範圍可選。
以下爲幾種常用的命名：

• 頁面標題，命名格式爲：title_頁面
• 按鈕文字，命名格式爲：btn_按鈕事件
• 標籤文字，命名格式爲：label_標籤文字
• 選項卡文字，命名格式爲：tab_選項卡文字
• 消息框文字，命名格式爲：toast_消息
• 編輯框的提示文字，命名格式爲：hint_提示信息
• 圖片的描述文字，命名格式爲：desc_圖片文字
• 對話框的文字，命名格式爲：dialog_文字
• menu的item文字，命名格式爲：action_文字

10. colors的命名

前綴{_控件}{_範圍}{_後綴}，控件、範圍、後綴可選，但控件和範圍至少要有一個。

• 背景顏色，添加bg前綴
• 文本顏色，添加text前綴
• 分割線顏色，添加div前綴
• 區分狀態時，默認狀態的顏色，添加normal後綴
• 區分狀態時，按下時的顏色，添加pressed後綴
• 區分狀態時，選中時的顏色，添加selected後綴
• 區分狀態時，不可用時的顏色，添加disable後綴

11. drawable的命名

前綴{_控件}{_範圍}{_後綴}，控件、範圍、後綴可選，但控件和範圍至少要有一個。

• 圖標類，添加ic前綴
• 背景類，添加bg前綴
• 分隔類，添加div前綴
• 默認類，添加def前綴
• 區分狀態時，默認狀態，添加normal後綴
• 區分狀態時，按下時的狀態，添加pressed後綴
• 區分狀態時，選中時的狀態，添加selected後綴
• 區分狀態時，不可用時的狀態，添加disable後綴
• 多種狀態的，添加selector後綴（一般爲ListView的selector或按鈕的selector）

12. 動畫文件命名

動畫類型_動畫方向。

• fade_in，淡入
• fade_out，淡出
• push_down_in，從下方推入
• push_down_out，從下方推出
• slide_in_from_top，從頭部滑動進入
• zoom_enter，變形進入
• shrink_to_middle，中間縮小

註釋規範

1. 文件頭註釋

文件頂部統一添加版權聲明，聲明的格式如下：

/**
 * Copyright (c) 2015. Keegan小鋼 Inc. All rights reserved.
 */

2. 類和接口註釋

類和接口統一添加javadoc註釋，格式如下：

/**
 * 類或接口的描述信息
 *
 * @author ${USER}
 * @date ${DATE}
 */

3. 方法註釋

下面幾種方法，都必須添加javadoc註釋，說明該方法的用途和參數說明，以及返回值的說明。

• 接口中定義的所有方法
• 抽象類中自定義的抽象方法
• 抽象父類的自定義公用方法
• 工具類的公用方法

/**
 * 登錄
 *
 * @param loginName 登錄名
 * @param password  密碼
 * @param listener  回調監聽器
 */
public void login(String loginName, String password, ActionCallbackListener<Void> listener);

4. 變量和常量註釋

下面幾種情況下的常量和變量，都要添加註釋說明，優先採用右側//來註釋，若註釋說明太長則在上方添加註釋。

• 接口中定義的所有常量
• 公有類的公有常量
• 枚舉類定義的所有枚舉常量
• 實體類的所有屬性變量

public static final int TYPE_CASH = 1; // 現金券
public static final int TYPE_DEBIT = 2; // 抵扣券
public static final int TYPE_DISCOUNT = 3; // 折扣券

private int id;                // 券id
private String name;           // 券名稱
private String introduce;      // 券簡介

---

結束語

這份開發規範說明比較細，也許還不是非常完整，但裏面提到的每一條規範都很有用。按照此規範嚴格執行，將大大提高代碼的可讀性和維護性。