一份小組協同開發可以使用的 Android 代碼規范
Chuxin Android Coding Style & 以前在公司的代碼規范，可在組內推行
1 Project structure 工程結構
1.1 Notice 說明
New projects should follow the Android Gradle project structure that is defined on the Android Gradle plugin user guide . The BoilerPlate project is a good reference.
新建工程需要按照最新的Android Gradle的工程結構,在以下定義： Android Gradle plugin user guide . 該工程： BoilerPlate 是一個很好的參考材料
1.2 Resources directory structure 資源文件夾結構
- res
- anim
- drawable (xml or selector)
- mipmap (pixel image)
- layout
- values
2 Package Manner 包管理規范
2.1 General 通用
- package name ： com.chuxin.[project name]
2.2 App 包結構
* app* (class) Constant [后續有文件說明] * (class) Application- ui
- fragment
- activity
- base
- dialog
- adapter
- custom
- service
- (which servie) ...
- entity
- local
- remote
- manager
- (which manager) ...
- util
- (which util)...</code></pre>
3 File Naming 文件命名
3.1 Class files 類文件命名
Class names are written in UpperCamelCase .
For classes that extend an Android component, the name of the class should end with the name of the component; for example: SignInActivity , SignInFragment , ImageUploaderService , ChangePasswordDialog .
For utilties class , the name of the class should start with its usage , and ends with Utils ; for example: HttpUtils , ImageUtils
類命名方式采用 大駝峰 命名法
對于繼承自安卓組件的類來說，類名應該以該組件名結尾，例如 ： SignInActivity , SignInFragment , ImageUploaderService , ChangePasswordDialog .
對于工具類來說，命名方式應該以其完成功能開始,以 Utils 結束 ，例如 ： HttpUtils , ImageUtils .
3.2 Resources files 資源文件
Resources file names are written in lowercase_underscore .
資源文件以__小寫加下劃線__的方式命名
3.3 Drawable files
- Naming conventions for drawables:
drawable 文件的命名規范
Asset Type Prefix 前綴 Example Action bar ab_ ab_stacked.9.png Button btn_ btn_send_pressed.9.png Dialog dialog_ dialog_top.9.png Divider divider_ divider_horizontal.9.png Icon ic_ ic_star.png Menu menu_ menu_submenu_bg.9.png Notification notification_ notification_bg.9.png Tabs tab_ tab_pressed.9.png - Naming conventions for icons:
icons文件的命名規范
Asset Type Prefix 前綴 Example Icons ic_ ic_star.png Launcher icons ic_launcher ic_launcher_calendar.png Menu icons and Action Bar icons ic_menu ic_menu_archive.png Status bar icons ic_stat_notify ic_stat_notify_msg.png Tab icons ic_tab ic_tab_recent.png Dialog icons ic_dialog ic_dialog_info.png - Naming conventions for selector states:
選擇器狀態文件的命名規范
State Suffix 尾綴 Example Normal _normal btn_order_normal.9.png Pressed _pressed btn_order_pressed.9.png Focused _focused btn_order_focused.9.png Disabled _disabled btn_order_disabled.9.png Selected _selected btn_order_selected.9.png 3.4 Layout files 布局文件
Layout files should match the name of the Android components that they are intended for but moving the top level component name to the beginning. For example, if we are creating a layout for the SignInActivity , the name of the layout file should be activity_sign_in.xml .
布局文件的命名需要與他所嵌入的安卓組件匹配，但是將組件名稱前移到開始處,例如,我們要創建一個名字為 SignInActivity , 其名字應該為 activity_sign_in.xml .
Component 組件 Class Name Layout Name Activity UserProfileActivity activity_user_profile.xml Fragment SignUpFragment fragment_sign_up.xml Dialog ChangePasswordDialog dialog_change_password.xml AdapterView Item --- item_person.xml 4 Inside Code Naming 代碼內部命名
Important ： 請不要使用拼音以及數字！！！
- (which util)...</code></pre>
====== 常用縮寫 ======
完整單詞 縮寫
A average ——> avg
B back ——> bk background ——> bg break ——> brk buffer ——> buf
C color ——> cr(clr) control ——> ctrl
D data ——> dat delete ——> del document ——> doc
E edit ——> edt error ——> err escape ——> esc
F flag ——> flg form ——> frm
G grid ——> grd
I increment ——> inc information ——> info initial ——> init insert ——> ins image ——> img
L label ——> lab length ——> len list ——> lst library ——> lib
M manager ——> mngr(mgr) message ——> msg
O Oracle ——> Ora
P panorama ——> pano password ——> pwd picture ——> pic point ——> pt position ——> pos print ——> prn program ——> prg
S server ——> srv source ——> src statistic ——> stat string ——> str Sybase ——> Syb
T temp ——> tmp text ——> txt
U user ——> usr
W window ——> wnd(win)</code></pre>
4.1 Class Variable Naming 類變量命名
- 公有變量按 小駝峰 法命名
- 私有 & 非靜態成員變量以 m 開頭
- 私有 & 靜態成員變量以 s 開頭
- 常量以大寫字母和下劃線 _ 組成
- 盡量使用 功能/描述 + 類型 的模式 ,如 mNameTextView
- 類中變量的組件類型請不要使用縮寫
- 注意不要使用 aa bb cc3 這種變態的命名方式 ！！
- 類變量過多時請 分塊擺放 并且 寫好注釋
- 接口類 請直接定義在類的最后
Example:
public class MyClass { //靜態常量 public static final int SOME_CONSTANT = 42; //公有變量 public int publicField; //私有靜態變量 private static MyClass sSingleton; //默認變量 int mPackagePrivate; //私有變量 private int mPrivate; //繼承型變量 protected int mProtected; }4.2 Class Method Naming 類方法命名
- 類方法采用 小駝峰 命名法
- 根據函數所完成功能命名 ， 如 changView()
- 在函數頭寫對于函數功能、參數和返回值的注釋，如：
/*** 獲取兩個數中最大的一個 * * @param value1 參與比較的第一個數 * @param value2 參與比較的第二個數 * @return 兩個參數中最大的一個數 */public int max(int value1, int value2) { return (value1 > value2) ? value1 : value2; }</code></pre>
- 一個函數請盡量保持在 50行 之內 ！！
4.3 layout.xml 布局文件變量命名
- id 以 所在組件_類型_命名 的模式，例如： @+id/main_tv_name 、 @id/chat_btn_send
- 布局多處重用的請使用 <include> 標簽
- 所有文本請定義在 strings.xml 中 , 如 @string/app_name
- 重用dp請定義在 dimens.xml 中 , 如 @dimen/entry_item_height
- 對應組件縮寫表：
Component 組件 Abbreviation 縮寫 Fragment fgm TextView tv ImageView iv Button btn EditText et LinearLayout ll ReleativeLayout rl normally : FirstSecond fs 4.4 strings.xml dimens.xml colors.xml xml變量命名
- 遵循 完整性 規范性 有序性 原則
- 分塊并注釋 , 將 使用在不同的 Activity 或者 Fragment 中的 xml 變量 進行分塊
- 命名舉例 ： login_error_tips in strings.xml
login_error_tips_height in dimens.xml login_error_tips_bg in colors.xml
Prefix 前綴 Description 描述 error_ An error message msg_ A regular information message title_ A title, i.e. a dialog title action_ An action such as "Save" or "Create" 4.5 額外注意
Good Bad XmlHttpRequest XMLHTTPRequest getCustomerId getCustomerID String url String URL long id long ID 5 Code Manner 代碼規范
This is good
if (condition){ body(); }This is bad :
if (condition) body(); // bad!This is good :
<TextView android:id="@+id/text_view_profile" android:layout_width="wrap_content" android:layout_height="wrap_content" />This is bad :
<!-- Don't do this! --> <TextView android:id="@+id/text_view_profile" android:layout_width="wrap_content" android:layout_height="wrap_content" > </TextView>6 Constant 內部類解析
- Constant * CODE --> request_code ， app_key 等 * CONFIG --> 項目的配置變量, 偏向于調試開發使用，如： IS_DEBUG , SHOW_LOG * URL --> 網絡地址相關 * COUNT --> 某些約定的數字，如一次刷新顯示的條目數量。 一定要有注釋 * PATH --> 路徑信息，SD卡路徑等 * KEY --> 鍵值對的鍵的信息,如 Bundle 中的鍵
7 Git 提交規范
基本要求
- 分段
例子：
(Git test) Modify CircleImageView to show rounded rectangleThe original function can be used normally, To show rounded rectangle, you need add param "bao:round" to XML file, it's value is the rounded rectangle's corner radius.</code></pre>
第一行: 作為標題，這在 Git 中就會做為默認顯示的部分，如圖中深黑色字：
第二行: 留空！因為通常在設置了郵件提醒的 Git 系統中，第二行的空行是作為分隔標題和正文的存在。
第三行: 開始就是詳細說明了。可以加上對此次修改的問題的鏈接，或者描述。如果有用到 issue 的話可以寫上 issue #[issue id] ，或者附上 trello 的鏈接。
建議全部用英文寫，其他字符有亂碼的可能。
并不會亂碼
- 粒度
說的是做的修改的粒度。如果你一天做了很多的修改，但是就只提交了一次，那么你的粒度就有點大了。
這樣在你描述你的行為的時候就會顯得模糊，如果你詳細描述的話，提交信息會變得長篇大論。
但也不要做一點提交一點，這樣粒度就會變得太小，會導致一天到晚在寫提交信息，沒有必要。
在我看來，這個事情真的只能憑感覺提交，用經驗來做判斷。因為一個BUG可能可大可小，大的話，你就得分割修復。
如果小，那么就一次提交修復就可。
粒度的掌握絕對會影響你的提交信息，因為二者是一一對應的。
- 寬度
是的，是寬度，不是長度。
和代碼一樣，如果你平時注意的話，就不要讓你的代碼在一行上超過80，不然誰讀代碼都不好受，包括你自己。
所以提交信息的寬度也有限制。
分別是標題不要超過50，內容部分不要超過70。
大概大家都會的沒什么用的小Tips：
- 使用 git commit 命令并進入 Vim 編輯提交信息，寫完后按 Esc 確保不在編輯狀態，然后輸入 :wq 回車退出并提交。
- 直接使用 Android Studio 自帶的 VCS 也很方便。
參考資料：
項目主頁：http://www.baiduhome.net/lib/view/home/1490252199221