Android開發規范 · 凡普金科開發規范

# 安卓開發規范(updating) ## 版本日志 * 17/03/30: 發布初版; ## 摘要 * [1 前言](#1-前言) * [2 AS規范](#2-as規范) * [3 命名規范](#3-命名規范) * [4 資源文件規范](#4-資源文件規范) * [5 版本統一規范](#5-版本統一規范) * [6 第三方庫規范](#6-第三方庫規范) * [7 注釋規范](#7-注釋規范) * [8 測試規范](#8-測試規范) * [9 RN規范](#9-RN規范) * [10 其他的一些規范](#10-其他的一些規范) ### 1 前言為了利于項目維護以及規范開發，促進成員之間Code Review的效率，故提出以下開發規范，如有更好建議，歡迎到GitHub提issue，原文地址： **[安卓開發規范(updating)][安卓開發規范(updating)]** ### 2 AS規范工欲善其事，必先利其器。 1. 盡量使用最新版的IDE進行開發； 2. 編碼格式統一為**UTF-8**； 3. 編輯完`.java`、 `.xml`等文件后一定要**格式化**（基本格式方面使用 AS 默認模板即可）； 4. 刪除多余的import，減少警告出現，可利用AS的`Optimize Imports`(Settings → Keymap → Optimize Imports)快捷鍵； 5. AS常用開發插件可以參考這里～**[AS常用開發插件][AS常用開發插件]** ### 3 命名規范代碼中的命名嚴禁使用拼音與英文混合的方式,更不允許直接使用中文的方式。正確的英文拼寫和語法可以讓閱讀者易于理解,避免歧義。 > 注意：即使純拼音命名方式也要避免采用。但`alibaba`、`taobao`、`youku`、`hangzhou`等國際通用的名稱,可視同英文。 #### 3.1 包名包名全部小寫，連續的單詞只是簡單地連接起來，不使用下劃線，采用反域名命名規則，全部使用小寫字母。一級包名是頂級域名，通常為`com`,`edu`,`gov`,`net`,`org`等，二級包名為公司名，三級包名根據應用進行命名，后面就是對包名的劃分了，關于包名的劃分，推薦使用按功能分，一開始我們也是按照層去分包的，很坑爹。按照功能分可能你不是很好區分在哪個功能中，不過也比你按照層區分要好找很多。具體可以參考這篇博文～**[Package by features, not layers][Package by features, not layers]**，當然，我們大谷歌也有相應的sample～**[iosched][iosched]**，其結構如下所示，很值得學習。 ``` java └─com └─google └─samples └─apps └─iosched │ AppApplication.java 定義Application類 │ Config.java 定義配置數據（常量） │ ├─about │ AboutActivity.java │ ├─appwidget │ ScheduleWidgetProvider.java │ ScheduleWidgetRemoteViewsService.java │ ├─debug │ │ DebugAction.java │ │ DebugActivity.java │ │ DebugFragment.java │ │ │ └─actions │ DisplayUserDataDebugAction.java │ ForceAppDataSyncNowAction.java │ ForceSyncNowAction.java │ ... │ ├─explore │ │ ExploreIOActivity.java │ │ ExploreIOFragment.java │ │ ExploreModel.java │ │ ... │ │ │ └─data │ ItemGroup.java │ LiveStreamData.java │ MessageData.java │ ... │ ├─feedback │ FeedbackApiHelper.java │ FeedbackConstants.java │ FeedbackHelper.java │ ... │ ├─framework │ FragmentListener.java │ LoaderIdlingResource.java │ Model.java │ ...定義interface并實現 │ ├─gcm │ │ GCMCommand.java │ │ GCMIntentService.java │ │ GCMRedirectedBroadcastReceiver.java │ │ ... │ │ │ └─command │ AnnouncementCommand.java │ NotificationCommand.java │ SyncCommand.java │ ... │ ├─io │ │ BlocksHandler.java │ │ HandlerException.java │ │ HashtagsHandler.java │ │ ...處理model │ │ │ ├─map │ │ └─model │ │ MapData.java │ │ Marker.java │ │ Tile.java │ │ │ └─model │ Block.java │ DataManifest.java │ Hashtag.java │ ... │ ├─map │ │ InlineInfoFragment.java │ │ MapActivity.java │ │ MapFragment.java │ │ ... │ │ │ └─util │ CachedTileProvider.java │ MarkerLoadingTask.java │ MarkerModel.java │ ... │ ├─model │ ScheduleHelper.java │ ScheduleItem.java │ ScheduleItemHelper.java │ ...定義model以及實現model相關操作 │ ├─myschedule │ MyScheduleActivity.java │ MyScheduleAdapter.java │ MyScheduleFragment.java │ ... │ ├─provider │ ScheduleContract.java │ ScheduleContractHelper.java │ ScheduleDatabase.java │ ...實現ContentProvider │ （也在此處定義provider依賴的其它類，比如db操作） │ ├─receiver │ SessionAlarmReceiver.java │ ├─service │ DataBootstrapService.java │ SessionAlarmService.java │ SessionCalendarService.java │ ├─session │ SessionDetailActivity.java │ SessionDetailConstants.java │ SessionDetailFragment.java │ ... │ ├─settings │ ConfMessageCardUtils.java │ SettingsActivity.java │ SettingsUtils.java │ ├─social │ SocialActivity.java │ SocialFragment.java │ SocialModel.java │ ├─sync │ │ ConferenceDataHandler.java │ │ RemoteConferenceDataFetcher.java │ │ SyncAdapter.java │ │ ... │ │ │ └─userdata │ │ AbstractUserDataSyncHelper.java │ │ OnSuccessListener.java │ │ UserAction.java │ │ ... │ │ │ ├─gms │ │ DriveHelper.java │ │ GMSUserDataSyncHelper.java │ │ │ └─util │ UserActionHelper.java │ UserDataHelper.java │ ├─ui │ │ BaseActivity.java │ │ CheckableLinearLayout.java │ │ SearchActivity.java │ │ ...BaseActivity以及自定義UI組件 │ │ │ └─widget │ AspectRatioView.java │ BakedBezierInterpolator.java │ BezelImageView.java │ ...自定義小UI控件 │ ├─util │ AboutUtils.java │ AccountUtils.java │ AnalyticsHelper.java │ ...工具類，提供靜態方法 │ ├─videolibrary │ VideoLibraryActivity.java │ VideoLibraryFilteredActivity.java │ VideoLibraryFilteredFragment.java │ ... │ └─welcome AccountFragment.java AttendingFragment.java ConductFragment.java ... ``` 參考Google I/O 2015的代碼結構，按功能分包具體可以這樣做： ``` src └─com └─domain └─app │ AppApplication.java 定義Application類 │ Config.java 定義配置數據（常量） │ ├─framework │ 定義interface以及相關基類 │ ├─io │ 數據定義（model）、數據操作（比如json解析，但不包括db操作） │ ├─model │ 定義model（數據結構以及getter/setter、compareTo、equals等等，不含復雜操作） │ 以及modelHelper（提供便于操作model的api） │ ├─provider │ 實現ContentProvider，及其依賴的db操作 │ ├─receiver │ 實現Receiver │ ├─service │ 實現Service（比如IntentService），用于在獨立線程中異步do stuff │ ├─ui │ 實現BaseActivity，以及自定義view和widget，相關的Adapter也放這里 │ ├─util │ 實現工具類，提供靜態方法 │ ├─feature1 │ Item.java 定義model │ ItemHelper.java 實現modelHelper │ feature1Activity.java 定義UI │ feature1DAO.java 私有db操作 │ feature1Utils.java 私有工具函數 │ ...其它私有class │ ├─...其它feature ``` 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太多）表示這塊需要重構（劃分子包） #### 3.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為前綴，不加后綴，其他的接口采用上述命名規則。 #### 3.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前綴標識 | #### 3.4 常量名常量名命名模式為`CONSTANT_CASE`，全部字母大寫，用下劃線分隔單詞。那，到底什么算是一個常量？每個常量都是一個靜態`final`字段，但不是所有靜態`final`字段都是常量。在決定一個字段是否是一個常量時，考慮它是否真的感覺像是一個常量。例如，如果任何一個該實例的觀測狀態是可變的，則它幾乎肯定不會是一個常量。只是永遠不打算改變對象一般是不夠的，它要真的一直不變才能將它示為常量。 ```java // Constants static final int NUMBER_AAA = 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`風格的基礎上改造為如下風格：基本結構為`scopeVariableNameType`。 **scope：范圍** 非公有，非靜態字段命名以m開頭。靜態字段命名以s開頭。例子： ```java public class MyClass { int mPackagePrivate; private int mPrivate; protected int mProtected; private static MyClass sSingleton; } ``` 使用1字符前綴來表示作用范圍，1個字符的前綴必須小寫，前綴后面是由表意性強的一個單詞或多個單詞組成的名字，而且每個單詞的首寫字母大寫，其它字母小寫，這樣保證了對變量名能夠進行正確的斷句。 **Type：類型** 考慮到Android中使用很多UI控件，為避免控件和普通成員變量混淆以及更好達意，所有用來表示控件的成員變量統一加上控件縮寫作為后綴（文末附有縮寫表）。對于普通變量一般不添加類型后綴，如果統一添加類型后綴，請參考文末的縮寫表。用統一的量詞通過在結尾處放置一個量詞，就可創建更加統一的變量，它們更容易理解，也更容易搜索。 > 注意：如果項目中使用`ButterKnife`，則不添加m前綴，以`lowerCamelCase`風格命名。例如，請使用`mCustomerStrFirst`和`mCustomerStrLast`，而不要使用`mFirstCustomerStr`和`mLastCustomerStr`。 | 量詞列表 | 量詞后綴說明 | | ----- | ----------- | | First | 一組變量中的第一個 | | Last | 一組變量中的最后一個 | | Next | 一組變量中的下一個變量 | | Prev | 一組變量中的上一個 | | Cur | 一組變量中的當前變量 | 說明：集合添加如下后綴：List、Map、Set 數組添加如下后綴：Arr > 注意：所有的VO（值對象）統一采用標準的lowerCamelCase風格編寫，所有的DTO（數據傳輸對象）就按照接口文檔中定義的字段名編寫。 #### 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 類名](#32-類名))，后面加個大寫的`T`(如：`RequestT`, `FooBarT`)。更多還可參考～**[阿里巴巴Java開發手冊][阿里巴巴Java開發手冊]** ### 4 資源文件規范 #### 4.1 資源布局文件（XML文件（layout布局文件））全部小寫，采用下劃線命名法 ##### 4.1.1 contentView命名必須以全部單詞小寫，單詞間以下劃線分割，使用名詞或名詞詞組。所有Activity或Fragment的contentView必須與其類名對應，對應規則為：將所有字母都轉為小寫，將類型和功能調換（也就是后綴變前綴）。例如：布局命名：——————————— `activity_main.xml` fragment_main.xml view_titlebar_xx.xml <ListView-Item> item_main_book.xml viewId命名：控件名稱，歸屬地，作用 ,下劃線。 @+id/iv_main_login 自定義控件 @+id/titlebar_reresh ImageView mIvMainLogin; ##### 4.1.2 Dialog命名規則：`dialog_描述.xml` 例如：`dialog_hint.xml` ##### 4.1.3 PopupWindow命名規則：`ppw_描述.xml` 例如：`ppw_info.xml` ##### 4.1.4 列表項命名規則：`item_描述.xml` 例如：`item_city.xml` ##### 4.1.5 包含項命名規則：`模塊_(位置)描述.xml` 例如：`activity_main_head.xml`、`activity_main_bottom.xml` 注意：通用的包含項命名采用：`項目名稱縮寫_描述.xml` 例如：`xxxx_title.xml` #### 4.2 資源文件（圖片drawable文件夾下）全部小寫，采用下劃線命名法，加前綴區分命名模式：可加后綴?`_small`?表示小圖，?`_big`?表示大圖，邏輯名稱可由多個單詞加下劃線組成，采用以下規則： * `用途_模塊名_邏輯名稱` * `用途_模塊名_顏色` * `用途_邏輯名稱` * `用途_顏色` 說明：用途也指控件類型（具體見附錄[UI控件縮寫表](#ui控件縮寫表)）例如： | 名稱 | 說明 | | ----------------------- | ----------------------- | | 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 | 列表分割線`用途_邏輯名稱` | | sel_search_ok | 搜索界面確認選擇器`用途_模塊名_邏輯名稱` | | shape_music_ring | 音樂界面環形形狀`用途_模塊名_邏輯名稱` | 如果有多種形態，如按鈕選擇器：`sel_btn_xx.xml` | 名稱 | 說明 | | -------------------- | ---------------------------- | | sel_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，前提是命名要規范。 #### 4.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 | 中間縮小 | #### 4.4 values中name命名 ##### 4.4.1 colors.xml `colors.xml`的`name`命名使用下劃線命名法，在你的`colors.xml`文件中應該只是映射顏色的名稱一個ARGB值，而沒有其它的。不要使用它為不同的按鈕來定義ARGB值。 **不要這樣做** ```xml <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`, 應該放到一個按鈕風格中，而不是在`colors.xml`文件中。 **相反，這樣做** ```xml <resources>  <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>  <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來說，減少使用顏色的種類是非常重要的。 > 注意：如果某些顏色和主題有關，那就單獨寫一個`colors_theme.xml`。 ##### 4.4.2 dimens.xml 像對待`colors.xml`一樣對待`dimens.xml`文件與定義顏色調色板一樣，你同時也應該定義一個空隙間隔和字體大小的“調色板”。一個好的例子，如下所示： ```xml <resources>  <dimen name="font_larger">22sp</dimen> <dimen name="font_large">18sp</dimen> <dimen name="font_normal">15sp</dimen> <dimen name="font_small">12sp</dimen>  <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>  <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`字符串一樣直接寫值。這樣寫會非常有感覺，會使組織和改變風格或布局是非常容易。 ##### 4.4.3 strings.xml `strings`的`name`命名使用下劃線命名法，采用以下規則：`模塊名+邏輯名稱`，這樣方便同一個界面的所有string都放到一起，方便查找。 | 名稱 | 說明 | | ----------------- | ------- | | main_menu_about | 主菜單按鍵文字 | | friend_title | 好友模塊標題欄 | | friend_dialog_del | 好友刪除提示 | | login_check_email | 登錄驗證 | | dialog_title | 彈出框標題 | | button_ok | 確認鍵 | | loading | 加載文字 | ##### 4.4.4 styles.xml `style`的`name`命名使用大駝峰命名法，幾乎每個項目都需要適當的使用`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`中。 **將一個大的`styles.xml`文件分割成多個文件**，?你可以有多個`styles.xml`?文件。Android SDK支持其它文件，`styles.xml`這個文件名稱并沒有作用，起作用的是在文件里的`<style>`標簽。因此你可以有多個style文件，如`styles.xml`、`styles_home.xml`、`styles_item_details.xml`、`styles_forms.xml`。不同于資源文件路徑需要為系統構建起的有意義，在`res/values`目錄下的文件可以任意命名。 #### 4.5 layout中的id命名命名模式為：`view縮寫_模塊名_邏輯名`，比如`btn_main_search` 使用`AndroidStudio`的插件`ButterKnife Zelezny`，生成注解非常方便，原生的話可以使用`Android Code Generator`插件。如果想對資源文件進行分包可以參考我這篇文章～**[Android Studio下對資源進行分包][Android Studio下對資源進行分包]** ### 5 版本統一規范 Android開發存在著眾多版本的不同，比如`compileSdkVersion`、`minSdkVersion`、`targetSdkVersion`以及項目中依賴第三方庫的版本，不同的module及不同的開發人員都有不同的版本，所以需要一個統一版本規范的文件。具體可以參考我寫的這篇博文～**[Android開發之版本統一規范][Android開發之版本統一規范]** ### 6 第三方庫規范別再閉門造車了，用用最新最火的技術吧，安利一波～**[Android 流行框架查速表][Android 流行框架查速表]**，順便帶上自己的干貨～**[Android開發人員不得不收集的代碼][Android開發人員不得不收集的代碼]** 希望Team能用時下較新的技術，對開源庫的選取，一般都需要選擇比較穩定的版本，作者在維護的項目，要考慮作者對issue的解決，以及開發者的知名度等各方面。選取之后，一定的封裝是必要的。個人推薦Team可使用如下優秀輪子： * **[Retrofit][Retrofit]** * **[RxAndroid][RxAndroid]** * **[OkHttp][OkHttp]** * **[Glide][Glide]** / **[Fresco][Fresco]** * **[Gson][Gson]** / **[Fastjson][Fastjson]** * **[EventBus][EventBus]** / **[AndroidEventBus][AndroidEventBus]** * **[GreenDao][GreenDao]** * **[Dagger2][Dagger2]**(選用) * **[Tinker][Tinker]**(選用) ### 7 注釋規范為了減少他人閱讀你代碼的痛苦值，請在關鍵地方做好注釋。 #### 7.1 類注釋每個類完成后應該有作者姓名和聯系方式的注釋，對自己的代碼負責。 ```java /** * <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，輸入 ```java /** * <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便會幫你生成模板，我們只需要補全參數即可，如下所示。 ```java /** * 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的。 ```java /* * This is // And so /* Or you can * okay. // is this. * even do this. */ */ ``` 注釋不要封閉在由星號或其它字符繪制的框架里。 > Tip：在寫多行注釋時，如果你希望在必要時能重新換行(即注釋像段落風格一樣)，那么使用`/* ... */`。 #### 7.4 其他一些注釋 AS已幫你集成了一些注釋模板，我們只需要直接使用即可，在代碼中輸入`todo`、`fixme`等這些注釋模板，回車后便會出現如下注釋 ``` java // TODO: 17/3/14 需要實現，但目前還未實現的功能的說明 // FIXME: 17/3/14 需要修正，甚至代碼是錯誤的，不能工作，需要修復的說明 ``` ### 8 測試規范業務開發完成之后，開發人員做單元測試，單元測試完成之后，保證單元測試全部通過同時單元測試代碼覆蓋率達到一定程度（這個需要開發和測試約定，理論上越高越好），開發提測。 // TODO... ### 9 RN規范 // TODO... ### 10 其他的一些規范 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. 盡可能使用局部變量； 13. 及時關閉流； 14. 盡量減少對變量的重復計算；如下面的操作： ``` java for (int i = 0; i < list.size(); i++) { ... } ``` 建議替換為： ``` java for (int i = 0, int length = list.size(); i < length; i++) { ... } ``` 15. 盡量采用懶加載的策略，即在需要的時候才創建；例如： ``` java String str = "aaa"; if (i == 1) { list.add(str); } ``` 建議替換為： ``` java 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）控制數據的共享，在不建立直接關聯的條件下，讓多個不相關的進程或線程之間實現通信 20. 把一個基本數據類型轉為字符串，`基本數據類型.toString()`是最快的方式、`String.valueOf(數據)`次之、`數據 + ""`最慢； 21. 使用AS自帶的Lint來優化代碼結構（什么，你不會？右鍵module、目錄或者文件，選擇Analyze → Inspect Code）； 22. 最后不要忘了內存泄漏的檢測； --- 最后啰嗦幾句： * 好的命名規則能夠提高代碼質量，使得新人加入項目的時候降低理解代碼的難度； * 規矩終究是死的，適合團隊的才是最好的； * 命名規范需要團隊一起齊心協力來維護執行，在團隊生活里，誰都不可能獨善其身； * 一開始可能會有些不習慣，持之以恒，總會成功的。 ## 附錄 ### UI控件縮寫表 | 名稱 | 縮寫 | | -------------- | ---- | | TextView | tv | | EditText | et | | ImageButton | ib | | Button | btn | | ImageView | iv | | ListView | lv | | GridView | gv | | ProgressBar | pb | | SeekBar | sb | | RadioButtion | rb | | CheckBox | cb | | ScrollView | sv | | LinearLayout | ll | | FrameLayout | fl | | RelativeLayout | rl | | RecyclerView | rv | | WebView | wv | | VideoView | vv | | Spinner | spn | | ToggleButton | tb | ### 常見的英文單詞縮寫表 | 名稱 | 縮寫 | | -------------------- | ---------------------------------------- | | icon | ic （主要用在app的圖標） | | color | cl（主要用于顏色值） | | average | avg | | background | bg（主要用于布局和子布局的背景） | | selector | sel主要用于某一view多種狀態，不僅包括Listview中的selector，還包括按鈕的selector） | | buffer | buf | | control | ctrl | | default | def | | delete | del | | document | doc | | error | err | | escape | esc | | increment | inc | | infomation | info | | initial | init | | image | img | | Internationalization | I18N | | length | len | | library | lib | | message | msg | | password | pwd | | position | pos | | server | srv | | string | str | | temp | tmp | | window | wnd(win) | 程序中使用單詞縮寫原則：不要用縮寫，除非該縮寫是約定俗成的。