簡單總結了 Android 開發中的一些代碼規範,供開發者參考。
1 命名規範
大駝峯命名(UpperCamelCase):每個單詞的第一個字母都大寫。
小駝峯命名(lowerCamelCase):除第一個單詞以外,每一個單詞的第一個字母大寫。
命名的基本原則:
- 不能以下劃線或美元符號開始,也不能以下劃線或美元符號結束。
- 嚴禁使用拼音與英文混合的方式,更不允許直接使用中文的方式。但比如
shanghai
等通用的名稱,可視同英文。 - 除了常見的英文縮寫,儘量避免縮寫。
1.1 類 / 接口命名
- 使用大駝峯命名法,用名詞或者名詞詞組命名,每個單詞的首字母大寫。
- 儘量避免大寫,除非該縮寫是衆所周知的,比如
URL
、HTML
等。 - 接口命名規則與類一樣採用大駝峯命名法,多以
able
或ible
結尾,如interfaceRunnable
、interfaceAccessible
。 - 若項目採用
MVP
架構,接口都以I
爲前綴,不加後綴,其他的接口採用上述命名規則。比如interfaceIUserTest
。 - 常見類名命名規則如下:
類 | 描述 | 舉例 |
---|---|---|
Activity 類 | 以 Activity 爲後綴 | 登錄頁面類 LoginActivity |
Fragment 類 | 以 Fragment 爲後綴 | 新聞標題列表 NewsTitlelFragment |
Service 類 | 以 Service 爲後綴 | 下載服務 DownloadService |
Adapter 類 | 以 Adapter 爲後綴 | 新聞詳情適配器 NewsDetailAdapter |
工具方法類 | 以 Utils 或 Manager 爲後綴 | 日誌工具 LogUtils |
數據庫類 | 以 DBHelper 爲後綴 | 新聞數據庫 NewsDBHelper |
解析類 | 以 Parser 爲後綴 | JSON 解析類 JsonParser |
BroadcastReceiver 類 | 以 Receiver 爲後綴 | 強制下線廣播 ForceOfflineReceiver |
自定義共享基礎類 | 以 Base 爲前綴 | BaseActivity、BaseFragment |
測試類 | 以它要測試的類的名稱開始,以 Test 結束 | UserTest |
抽象類 | 以 Abstract 或 Abs 爲前綴 | AbsUserTest |
1.2 變量命名
- 成員變量 / 局部變量
- 使用小駝峯命名。
- 不推薦使用谷歌的前面加
m
的編碼風格。 - 控件變量
- 使用小駝峯命名。
- 建議使用
控件縮寫+邏輯名稱
格式,例如btnLogin
、etUserName
。 - 對應的控件
id
命名爲控件縮寫_邏輯名稱
,例如btn_login
、et_user_name
。 - 常見控件縮寫如下:
控件 | 縮寫 | 控件 | 縮寫 |
---|---|---|---|
TextView | tv | ImageButton | ib |
EditText | et | CheckBox | cb |
WebView | wv | RadioButton | rb |
ImageView | iv | SeekBar | sb |
VideoView | vv | ProgressBar | pb |
MediaController | mc | Spinner | spr |
ListView | lv | SerachView | sev |
GridView | gv | Button | btn |
Gallery | gly | TimePicker | tp |
LinearLayout | ll | DatePicker | dp |
RelativeLayout | rl | ScrollView | sv |
FrameLayout | fl | RecyclerView | rv |
1.3 常量命名
- 單詞每個字母均大寫。
- 單詞之間用下劃線連接,力求語義表達完整清楚,不要嫌名字長。
1.4 方法命名
- 使用小駝峯命名。
- 方法名通常是動詞或動詞短語,保證見名知義,儘量不適用
or
或者and
,遵循 “ do one thing ” 原則。 - 一個方法儘量不要超過 50 行,如果方法太長,說明當前方法業務邏輯已經非常複雜,那麼就需要進行方法拆分。
方法 | 說明 | 方法 | 說明 |
---|---|---|---|
initXX() | 初始化相關方法 | resetXX() | 重置數據 |
onXX() | 回調方法 | clearXX() | 清除數據 |
getXX() | 具有返回值的獲取方法 | removeXX() | 移除數據或視圖 |
setXX() | 設置方法 | drawXX() | 繪製 |
isXX()/hasXX()/checkXX() | 布爾型的判斷方法 | displayXX()/showXX() | 展示、提示信息的方法 |
updateXX() | 更新數據 | handleXX()/processXX() | 對數據進行處理的方法 |
saveXX() | 保存數據 |
1.5 資源文件命名
全部小寫,採用下劃線命名法。
1.5.1 佈局文件命名(xml 文件)
以對應的類別名稱爲前綴,邏輯名稱在後,以下劃線連接。
佈局類型 | 佈局前綴 |
---|---|
Activity | activity_ |
Fragment | fragment_ |
Include | include_ |
Dialog | dialog_ |
PopupWindow | popup_ |
Menu | menu_ |
GridView 的item 佈局文件 | itemgrid |
ListView 的 item 佈局文件 | itemlist |
1.5.2 drawable 文件命名
以用途縮寫作爲前綴,邏輯名稱在後,以下劃線連接,區分狀態時,添加狀態後綴。
drawable | 規則 |
---|---|
圖標資源 | ic_ |
背景圖片 | bg_ |
按鈕圖片 | btn_ |
分隔線 | div_ |
默認類 | def_ |
區分狀態時,默認狀態 | _normal |
區分狀態時,按下時的狀態 | _pressed |
區分狀態時,選中時的狀態 | _selected |
區分狀態時,不可用時的狀態 | _disable |
區分狀態時,懸停效果 | _hovered |
區分狀態時,可選狀態 | _checkable |
1.5.3 動畫文件命名(anim 文件夾下)
規則:動畫類型_動畫方向。
名稱 | 說明 |
---|---|
fade_in | 淡入 |
fade_out | 淡出 |
pushdownin | 從下方推入 |
pushdownout | 從下方推出 |
push_left | 推向左方 |
slideinfrom_top | 從頭部滑動進入 |
zoom_enter | 變形進入 |
slide_in | 滑動進入 |
shrinktomiddle | 中間縮寫 |
1.5.4 values 中 name 命名
1.5.4.1 strings.xml
- 命名格式:xx 界面 + 邏輯功能 ,如
activity_home_welcome_str
。 - 建議把同一個界面的所有 String 都在一起,方便查找。
1.5.4.2 styles.xml
- 使用大駝峯命名法,主題可以命名爲
XXTheme
,控件的風格可以命名爲XXStyle
。
1.5.4.3 colors.xml
- 命名格式:color_16進制顏色值
- 不要爲某個控件指定特定顏色,比如
bg_login
,這樣非常容易重複定義顏色值。
<resources> <color name="red_FF432F">#FF432F</color> <color name="red_FF0000">#FF0000</color> </resources>
1.5.4.4 dimens.xml
- 可以和 colors.xml 中命名格式類似
- 必要時也可用”邏輯名稱_功能“ 命名
<resources> <!-- font sizes --> <dimen name="font_22">22sp</dimen> <dimen name="font_12">12sp</dimen> <!-- typical spacing between two views --> <dimen name="spacing_40">40dp</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> </resources>
2 註釋規範
類、類屬性、類方法的註釋必須使用 Javadoc 規範,使用 /** XXX */
格式,不得使用 // XXX
方式。
2.1 類和接口註釋
類和接口統一添加 Javadoc 註釋,要求至少寫出創建者、創建時間以及內容簡要說明。具體可以在 AS 中自己配製, Settings→Editor→FileandCodeTemplates→Includes→FileHeader
,格式如下:
/** * author : xxx * e-mail : xxx@xx * time : 2017/08/28 * desc : */
2.2 方法註釋
下面幾種方法,都必須添加 Javadoc 註釋,除了返回值、參數、異常說明外,還必須指出該方法做什麼事情,實現什麼功能。
- 接口中定義的所有方法
- 抽象類中自定義的抽象方法
- 抽象父類的自定義公用方法
- 工具類的公用方法
/** 方法的一句話概述 * 方法詳述(簡單方法可不必詳述) * @param s 說明參數含義 * @return 說明返回值含義 * @throws IOException 說明發生此異常的條件 * @throws NullPointerException 說明發生此異常的條件 */
2.3 變量和常量註釋
下面幾種情況下的常量和變量,都要添加註釋說明,優先採用右側 //
來註釋,若註釋說明太長則在上方添加註釋。
- 接口中定義的所有常量
- 公有類的公有常量
- 枚舉類定義的所有枚舉常量
- 實體類的所有屬性變量
2.4 方法體內代碼的註釋
- 方法內部單行註釋,在被註釋語句上方另起一行,使用
//
註釋。 - 方法內部多行註釋使用
/* ... */
註釋。 - 注意與代碼對齊,
*
及//
與其後文字之間空一格。 - 不要在方法內部使用 Javadoc 形式的註釋。
2.5 其他一些註釋
- 資源文件代碼註釋
<!-- 註釋內容 -->
- AS 已幫你集成了一些註釋模板,我們只需要直接使用即可,在代碼中輸入
todo
、fixme
等這些註釋模板,回車後便會出現如下注釋:
// TODO: 2017/8/28 需要實現,但目前還未實現的功能的說明 // FIXME: 2017/8/28 需要修正,甚至代碼是錯誤的,不能工作,需要修復的說明
3 格式規範
3.1 使用標準的大括號風格
- 大括號與
if,else,for,do,while
語句一起使用,即使只有一條語句(或是空),也應該把大括號寫上。 - 對於非空塊和塊狀結構,大括號遵循 Kernighan 和 Ritchie 風格(R & N)
- 左大括號前不換行
- 右大括號前換行
- 如果右大括號是一個語句、函數體或類的終止,則右大括號後換行;否則不換行。例如,如果右大括號後面是
else
或catch
,則不換行。
class MyClass { public void method() { if (condition()) { try { something(); } catch (ProblemException e) { recover(); } } } }
- 一個空的塊狀結構裏什麼也不包含,大括號可以簡潔地寫成
{}
,不需要換行。
3.2 限制代碼行的長度
- 每行代碼的長度不應該不超過 100 個字符。
- 例外:
package
和import
語句,不換行。 - 例外:註釋中包含了超過 100 個字符的命令示例或者 URL,爲了便於剪切和複製,其長度可以超過 100 個字符。
3.3 合理空白
- 垂直空白
- 方法體內的執行語句組、變量的定義語句組、不同的業務邏輯之間或者不同的語義之間插入一個空行。相同業務邏輯和語義之間不需要插入空行。
- 水平空白
- 左小括號和右小括號與字符之間不出現空格。
if/for/while/switch/do
等保留字與括號之間都必須加空格。- 任何二目、三目運算符的左右兩邊都需要加一個空格。
- 方法參數在定義和傳入時,多個參數逗號後邊必須加空格。
- 請使用快捷鍵
ctrl+alt+L
格式化代碼。