Android 你應該注意的開發規範

時間  2019-11-24
標籤 android 應該 注意 開發 規範 欄目 Android 简体版
原文   原文鏈接

本文由Blankj投稿。html

Blankjd的博客地址：java

http://www.jianshu.com/u/46702d5c6978android

 

爲了利於項目維護以及規範開發，促進成員之間Code Review的效率，故提出如下開發規範，若有更好建議，歡迎到GitHub提issue。

 

https://github.com/Blankj/AndroidStandardDevelop
ios

 

1git

AS規範

 

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

 

  1. 儘可能使用最新版的IDE進行開發；github

  2. 編碼格式統一爲UTF-8；web

  3. 編輯完.java、 .xml等文件後必定要格式化（基本格式方面使用 AS 默認模板便可）；數據庫

  4. 刪除多餘的import，減小警告出現，可利用AS的Optimize Imports(Settings → Keymap → Optimize Imports)快捷鍵；json

  5. AS經常使用開發插件能夠參考這裏～AS經常使用開發插件(http://www.jianshu.com/p/c76b0d8a642d)數組

     

2

命名規範

 

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

 

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

 

2.1 包名

 

包名所有小寫，連續的單詞只是簡單地鏈接起來，不使用下劃線，採用反域名命名規則，所有使用小寫字母。

 

一級包名是頂級域名，一般爲com,edu,gov,net,org等，二級包名爲公司名，三級包名根據應用進行命名，後面就是對包名的劃分了，關於包名的劃分，推薦使用按功能分，一開始咱們也是按照層去分包的，很坑爹。

 

按照功能分可能你不是很好區分在哪一個功能中，不過也比你按照層區分要好找不少。

 

具體能夠參考這篇博文～Package by features, not layers：

 

https://medium.com/@cesarmcferreira/package-by-features-not-layers-2d076df1964d#.mp782izhh

 

固然，咱們大谷歌也有相應的sample～iosched

 

https://github.com/google/iosched/tree/master/android/src/main/java/com/google/samples/apps/iosched

 

其結構很值得學習（本身clone看一下，太長了，在手機端不太好閱讀）。

 

參考Google I/O 2015的代碼結構，按功能分包具體能夠這樣作：

 

 

PBF(按功能分包Package By Feature)與PBL(按層分包Package By Layer)相比較有以下優點：

 

package內高內聚，package間低耦合

 

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

 

按class職能分層（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天然放在feautreA下，小李的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
        │MainServ.java

按照PBL，service包下的全部東西都是Controller，應該不須要Serv後綴，但實際上一般爲了碼起來方便，直接import service包，Serv後綴是爲了不引入的class和當前包下的class命名衝突。

 

固然，不用後綴也能夠，得寫清楚包路徑，好比new net.ayqy.service.Main()，麻煩；而PBF就很方便，無需import，直接new MainServ()便可。

 

package的大小有意義了

 

PBL中包的大小無限增加是合理的，由於功能越添越多；而PBF中包太大（包裏class太多）表示這塊須要重構（劃分子包）。

 

2.2 類名

 

類名都以UpperCamelCase風格編寫。

 

類名一般是名詞或名詞短語，接口名稱有時多是形容詞或形容詞短語。如今尚未特定的規則或行之有效的約定來命名註解類型。

 

名詞，採用大駝峯命名法，儘可能避免縮寫，除非該縮寫是衆所周知的， 好比HTML, URL，若是類名稱中包含單詞縮寫，則單詞縮寫的每一個字母均應大寫。

 

類 描述 例如

Activity 類

Activity爲後綴標識

歡迎頁面類WelcomeActivity

Adapter類

Adapter 爲後綴標識

新聞詳情適配器 NewDetailAdapter

解析類

Parser爲後綴標識

首頁解析類HomePosterParser

工具方法類

Utils或Manager爲後綴標識（與系統或第三方的Utils區分）或功能+Utils

線程池管理類：ThreadPoolManager日誌工具類：LogUtils（Logger也可）打印工具類：PrinterUtils

數據庫類

以DBHelper後綴標識

新聞數據庫：NewDBHelper

Service類

以Service爲後綴標識

時間服務TimeService

BroadcastReceiver類

以Receiver爲後綴標識

推送接收JPushReceiver

ContentProvider類

以Provider爲後綴標識

ShareProvider

自定義的共享基礎類

以Base開頭

BaseActivity,BaseFragment

 

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

 

接口（interface）：命名規則與類同樣採用大駝峯命名法，多以able或ible結尾，如：

interface Runnable、interface Accessible。

 

注意：若是項目採用MVP，全部Model、View、Presenter的接口都以I爲前綴，不加後綴，其餘的接口採用上述命名規則。

 

2.3 方法名

 

方法名都以lowerCamelCase風格編寫。

方法名一般是動詞或動詞短語。

 

方法 說明

initXX()

初始化相關方法,使用init爲前綴標識，如初始化佈局initView()

isXX() checkXX()

方法返回值爲boolean型的請使用is或check爲前綴標識

getXX()

返回某個值的方法，使用get爲前綴標識

setXX()

設置某個屬性值

handleXX()/processXX()

對數據進行處理的方法

displayXX()/showXX()

彈出提示框和提示信息，使用display/show爲前綴標識

updateXX()

更新數據

saveXX()

保存數據

resetXX()

重置數據

clearXX()

清除數據

removeXX()

移除數據或者視圖等，如removeView();

drawXX()

繪製數據或效果相關的，使用draw前綴標識

 

2.4 常量名

 

常量名命名模式爲CONSTANT_CASE，所有字母大寫，用下劃線分隔單詞。那，到底什麼算是一個常量？

 

每一個常量都是一個靜態final字段，但不是全部靜態final字段都是常量。在決定一個字段是不是一個常量時，考慮它是否真的感受像是一個常量。

 

例如，若是任何一個該實例的觀測狀態是可變的，則它幾乎確定不會是一個常量。只是永遠不打算改變對象通常是不夠的，它要真的一直不變才能將它示爲常量。

 

 

 

2.5 很是量字段名

 

很是量字段名以lowerCamelCase風格的基礎上改造爲以下風格：

 

基本結構爲scopeVariableNameType。

 

scope：範圍

 

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

靜態字段命名以s開頭。

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

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

 

例子：

 

 

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

 

Type：類型

 

考慮到Android中使用不少UI控件，爲避免控件和普通成員變量混淆以及更好達意，全部用來表示控件的成員變量統一加上控件縮寫做爲後綴（文末附有縮寫表）。

 

對於普通變量通常不添加類型後綴，若是統一添加類型後綴，請參考文末的縮寫表。

 

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

 

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

 

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

 

量詞列表 量詞後綴說明

First

一組變量中的第一個

Last

一組變量中的最後一個

Next

一組變量中的下一個變量

Prev

一組變量中的上一個

Cur

一組變量中的當前變量

 

說明：

集合添加以下後綴：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.以類命名方式(參考3.2 類名)，後面加個大寫的T(如：RequestT, FooBarT)。

 

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

https://102.alibaba.com/newsInfo.htm?newsId=6

 

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控件縮寫表）

 

http://www.jianshu.com/p/419f5357357d#ui%E6%8E%A7%E4%BB%B6%E7%BC%A9%E5%86%99%E8%A1%A8

 

例如：

 

名稱 說明

btn_main_home.png

按鍵用途_模塊名_邏輯名稱

divider_maket_white.png

分割線用途_模塊名_顏色

ic_edit.png

圖標用途_邏輯名稱

bg_main.png

背景用途_邏輯名稱

btn_red.png

紅色按鍵用途_顏色

btn_red_big.png

紅色大按鍵用途_顏色

ic_head_small.png

小頭像用途_邏輯名稱

bg_input.png

輸入框背景用途_邏輯名稱

divider_white.png

白色分割線用途_顏色

bg_main_head

主模塊頭部背景圖片用途_模塊名_邏輯名稱

def_search_cell

默認搜索界面單元圖片用途_模塊名_邏輯名稱

ic_more_help

更多幫助圖標用途_邏輯名稱

divider_list_line

列表分割線用途_邏輯名稱

selector_search_ok

搜索界面確認選擇器用途_模塊名_邏輯名稱

shape_music_ring

音樂界面環形形狀用途_模塊名_邏輯名稱

 

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

 

名稱 說明

btn_xx

按鈕圖片使用btn_總體效果（selector）

btn_xx_normal

按鈕圖片使用btn_正常狀況效果

btn_xx_pressed

按鈕圖片使用btn_點擊時候效果

btn_xx_focused

state_focused聚焦效果

btn_xx_disabled

state_enabled (false)不可用效果

btn_xx_checked

state_checked選中效果

btn_xx_selected

state_selected選中效果

btn_xx_hovered

state_hovered懸停效果

btn_xx_checkable

state_checkable可選效果

btn_xx_activated

state_activated激活的

btn_xx_windowfocused

state_window_focused

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

 

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

 

所有小寫，採用下劃線命名法，加前綴區分。

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

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

 

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

 

名稱 說明

fade_in

淡入

fade_out

淡出

push_down_in

從下方推入

push_down_out

從下方推出

push_left

推向左方

slide_in_from_top

從頭部滑動進入

zoom_enter

變形進入

slide_in

滑動進入

shrink_to_middle

中間縮小

 

3.4 values中name命名

 
3.4.1 colors.xml

 

colors的name命名使用下劃線命名法，在你的colors.xml文件中應該只是映射顏色的名稱一個ARGB值，而沒有其它的。不要使用它爲不一樣的按鈕來定義ARGB值。

 

不要這樣作

 

 

使用這種格式，你會很是容易的開始重複定義ARGB值，這使若是須要改變基本色變的很複雜。

 

同時，這些定義是跟一些環境關聯起來的，如button或者comment, 應該放到一個按鈕風格中，而不是在color.xml文件中。

 

相反，這樣作

 

 

嚮應用設計者那裏要這個調色板，名稱不須要跟"green"、"blue"等等相同。"brand_primary"、"brand_secondary"、"brand_negative"這樣的名字也是徹底能夠接受的。 

 

像這樣規範的顏色很容易修改或重構，會使應用一共使用了多少種不一樣的顏色變得很是清晰。 一般一個具備審美價值的UI來講，減小使用顏色的種類是很是重要的。

 

注意：若是某些顏色和主題有關，那就獨立出去寫。

 
3.4.2 dimens.xml

 

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

 

 

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

 
3.4.3 strings.xml

 

strings的name命名使用下劃線命名法，採用如下規則：模塊名+邏輯名稱，這樣方便同一個界面的全部string都放到一塊兒，方便查找。

 

名稱 說明

main_menu_about

主菜單按鍵文字

friend_title

好友模塊標題欄

friend_dialog_del

好友刪除提示

login_check_email

登陸驗證

dialog_title

彈出框標題

button_ok

確認鍵

loading

加載文字
 
3.4.4 styles.xml

 

style的name命名使用大駝峯命名法，幾乎每一個項目都須要適當的使用style文件，由於對於一個視圖來講有一個重複的外觀是很常見的，將全部的外觀細節屬性（colors、padding、font）放在style文件中。 

 

在應用中對於大多數文本內容，最起碼你應該有一個通用的style文件，例如：

 

 

應用到TextView中:

 

 

你或許須要爲按鈕控件作一樣的事情，不要中止在那裏。將一組相關的和重複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下對資源進行分包

 

http://www.jianshu.com/p/8e893581b9c7

 

4

版本統一規範

 

Android開發存在着衆多版本的不一樣，好比compileSdkVersion、minSdkVersion、targetSdkVersion以及項目中依賴第三方庫的版本，不一樣的module及不一樣的開發人員都有不一樣的版本，因此須要一個統一版本規範的文件。

具體能夠參考我寫的這篇博文～Android開發之版本統一規範

 

http://www.jianshu.com/p/db6ef4cfa5d1

 

 

5

第三方庫規範

 

別再閉門造車了，用用最新最火的技術吧，安利一波～Android 流行框架查速表(http://www.ctolib.com/cheatsheets-Android-ch.html)，順便帶上本身的乾貨～Android開發人員不得不收集的代碼

 

https://github.com/Blankj/AndroidUtilCode

 

 

但願Team能用時下較新的技術，對開源庫的選取，通常都須要選擇比較穩定的版本，做者在維護的項目，要考慮做者對issue的解決，以及開發者的知名度等各方面。選取以後，必定的封裝是必要的。

 

我的推薦Team可以使用以下優秀輪子：

 

  • Retrofit

  • RxAndroid

  • OkHttp

  • Glide / Fresco

  • Gson / Fastjson

  • EventBus / AndroidEventBus

  • GreenDao

  • Dagger2(選用)

  • Tinker(選用)

 

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便會幫你生成模板，咱們只須要補全參數便可，以下所示。

 

 

6.3 塊註釋

 

塊註釋與其周圍的代碼在同一縮進級別。它們能夠是/* ... */風格，也能夠是// ...風格(//後最好帶一個空格）。

 

對於多行的/* ... */註釋，後續行必須從*開始， 而且與前一行的*對齊。如下示例註釋都是OK的。

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

註釋不要封閉在由星號或其它字符繪製的框架裏。

 

Tip：在寫多行註釋時，若是你但願在必要時能從新換行(即註釋像段落風格同樣)，那麼使用/* ... */。

 

6.4 其餘一些註釋

 

AS已幫你集成了一些註釋模板，咱們只須要直接使用便可，在代碼中輸入todo、fixme等這些註釋模板，回車後便會出現以下注釋

// TODO: 17/3/14 須要實現，但目前還未實現的功能的說明
// FIXME: 17/3/14 須要修正，甚至代碼是錯誤的，不能工做，須要修復的說明

 

最後囉嗦幾句：

  • 好的命名規則可以提升代碼質量，使得新人加入項目的時候下降理解代碼的難度；

  • 規矩終究是死的，適合團隊的纔是最好的；

  • 命名規範須要團隊一塊兒齊心合力來維護執行，在團隊生活裏，誰都不可能獨善其身；

  • 一開始可能會有些不習慣，鍥而不捨，總會成功的。

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程