旗魚移動Android開發規範

時間 2019-12-01

標籤旗魚移動 android 開發規範欄目無線简体版

原文原文鏈接

旗魚移動Android開發規範java

撰寫: 旗魚移動Android開發組 android

旗魚移動科技有限公司所屬，未經容許不得私自傳播數據庫

第1版編程

2016年 5 月 3 日網絡

目錄框架

1、Android開發框架
ide

2、命名規範
函數

　　2.1 包（packages）命名規範
工具

　　2.2 類（classes）命名規範
佈局

　　2.3 方法（methods）

　　2.4 變量（variables）

　　2.5 常量（Constants）

　　2.6 資源文件（圖片drawable文件夾下）

　　2.7 資源佈局文件（XML文件（layout佈局文件））

　　2.8 資源佈局文件（layout中的id命名）

3、代碼規範

　　3.1 排版

　　3.2 註釋

4、XML規範

1、Android開發框架

　　旗魚移動Android開發項目統一採用公司Android開發框架。

2、命名規範

2.1 包（packages）命名規範

　　採用反域名命名規則，所有使用小寫字母。一級包名爲com，二級包名爲qiyu，三級包名根據應用進行命名，四級包名爲模塊名或層級名等。

包名	此包中包含
com.qiyu.應用名稱縮寫.ui.activity	頁面用到的Activity類 (activities層級名用戶界面層)
com.qiyu.應用名稱縮寫.ui.fragment	頁面用到的Fragment類
com.qiyu.應用名稱縮寫.adapter	頁面用到的Adapter類 (適配器的類)
com.qiyu.應用名稱縮寫.utils/tools	此包中包含：公共工具方法類（utils/tools模塊名）
com.qiyu.應用名稱縮寫.response.data	網絡請求返回response層級1
com.qiyu.應用名稱縮寫.response.bean	網絡請求返回response層級2
com.qiyu.應用名稱縮寫.response.entity	網絡請求返回response層級3
com.qiyu.應用名稱縮寫.bean/entity	此包中包含：元素類
com.qiyu.應用名稱縮寫.db	數據庫操做類
com.qiyu.應用名稱縮寫.view	自定義的View類等
com.qiyu.應用名稱縮寫.XXXX	其餘定義的包名

2.2 類（classes）命名規範

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

類	描述	示例
Activity 類	Activity爲後綴標識	歡迎頁面類WelcomeActivity
Adapter類	Adapte 爲後綴標識	新聞詳情適配器NewDetailAdapter
解析類	Data爲總體後綴標識，二層析類Bean爲後綴標識，三層爲Entity。	首頁解析類HomePosterData
公共方法類	Utils、Tools或Manager爲後綴標識（靈活運用）	線程池管理類：ThreadPoolManager 日誌工具類：旗魚點餐中爲L
Service類	以Service爲後綴標識	時間服務TimeService
BroadcastReceive類	以Receiver爲後綴標識	時間通知TimeReceiver
ContentProvider	以Provider爲後綴標識	時間共享TimeProvider
直接寫的共享基礎類	以Base開頭	BaseActivity,BaseFragment
............	............	.............

2.3 方法（methods）

　　動詞或動名詞，採用小駝峯命名法例如:onCreate(),run()。自定義方法定義爲private ，特別須要例外。

方法	說明
initXX()	初始化相關方法,使用init爲前綴標識，如初始化佈局initView()
isXX()	checkXX()方法返回值爲boolean型的請使用is或check爲前綴標識，有時必須以get開頭，如數據庫類裏。
getXX()	返回某個值的方法，使用get爲前綴標識
processXX()	對數據進行處理的方法，儘可能使用process爲前綴標識
displayXX()	彈出提示框和提示信息，使用display爲前綴標識
saveXX()	與保存數據相關的，使用save爲前綴標識
resetXX()	對數據重組的，使用reset前綴標識
clearXX()	清除數據相關的
removeXXX()	清除數據相關的
drawXXX()	繪製數據或效果相關的，使用draw前綴標識
initXX()	初始化相關方法,使用init爲前綴標識，如初始化佈局initView()
..........	.....................

2.4 變量（variables）

　　採用小駝峯命名法。類中控件名稱必須與xml佈局id保持一致。

　　用統一的量詞經過在結尾處放置一個量詞，就可建立更加統一的變量，它們更容易理解，也更容易搜索。例如，請使用strCustomerFirst和strCustomerLast，而不要使用strFirstCustomer和strLastCustomer。
量詞列表：量詞後綴說明
First   一組變量中的第一個
Last   一組變量中的最後一個
Next  一組變量中的下一個變量
Pre   一組變量中的上一個
Cur   一組變量中的當前變量

...... .................

2.5 常量（Constants）

　　所有大寫,採用下劃線命名法.例如：MIN_WIDTH。

2.6 資源文件（圖片drawable文件夾下）

　　所有小寫，採用下劃線命名法，加前綴區分，圖片命名遵照圖片命名規範，若有多種形態如按鈕，則命名方式如 bt_功能名_xx.selector(操做).xml等。

圖片文件名後綴	狀態說明
_normal	(default state)
_pressed	state_pressed
_focused	state_focused
_disabled	state_enabled (false)
_checked	state_checked
_selected	state_selected
_hovered	state_hovered
_checkable	state_checkable
_activated	state_activated
_windowfocused	state_window_focused

2.7 資源佈局文件（XML文件（layout佈局文件））

　　所有小寫，採用下劃線命名法。

模塊	命名規則	示例
Activity	activity_功能模塊_xx.xml	activity_main.xml、activity_order_detail.xml
Fragment	fragment_功能模塊_xx.xml	fragment_head.xml
Dialog	dialog_描述_xx.xml	dialog_hint.xml
PopupWindow	ppw_描述_xx.xml	ppw_info.xml
包含項include	include_模塊_xx.xml	include_head.xml
adapter的子佈局	item_功能模塊_xx.xml	item_main.xml
.........	...........	................

2.8 資源佈局文件（layout中的id命名）

　　命名模式爲：view縮寫_view的邏輯名稱_XX。如tv_name,tv_name_label。

　　View縮寫使用view中每一個大寫字母組合拼成小寫，如TextView寫成tv便可。

　　View的縮寫詳情示例以下：

控件	命名縮寫示例
TextView	tv
EditText	et
ImageView	iv
Button	bt
LinearLayout	ll
RelativeLayout	rl
RecycleView	rv
.........	...........

3、代碼規範

3.1 排版

3.1.1 程序塊要採用縮進風格編寫，縮進的空格數爲4個。

　　說明：對於由開發工具自動生成的代碼能夠有不一致。

3.1.2 編程語句長度設置成160個字符（非必須）。

3.1.3 不容許把多個短語句寫在一行中，即一行只寫一條語句。

　　示例：以下例子不符合規範。

　　rect.length = 0; rect.width = 0;

　　應以下書寫：

rect.length = 0;
rect.width = 0;

3.1.4 if、for、do、while、case、switch、default等語句自佔一行，且if、for、do、while等語句的執行語句部分不管多少都要加括號{}。

示例：以下例子不符合規範。
if (pUserCR == NULL) return;

    應以下書寫：
    if (pUserCR == NULL)
    {
       return;
    }

3.1.5 函數或過程的開始、結構的定義及循環、判斷等語句中的代碼都要採用縮進風格， case語句下的狀況處理語句也要聽從語句縮進要求。

3.1.6 程序塊的分界符（如大括號‘ {’和‘ }’）應各獨佔一行而且位於同一列，同時與引用它們的語句左對齊。在函數體的開始、類的定義、結構的定義、枚舉的定義以及if、 for、 do、 while、 switch、 case語句中的程序都要採用如上的縮進方式。

示例：以下例子不符合規範。

    for (...) {
       ... // program code
    }

    if (...)
      {
      ... // program code
      }

　　void example_fun( void )
　　{
　　... // program code
　　}

應書寫以下。

　　for (...)
　　{
　　　　... // program code
　　}

　　if (...)
　　{
　　　　... // program code
　　}

　　void example_fun( void )
　　{
　　　　... // program code
　　}

3.1.7 在兩個以上的關鍵字、變量、常量進行對等操做時，它們之間的操做符以前、以後或者先後要加空格；進行非對等操做時，若是是關係密切的當即操做符（如－>），後不該加空格。

　　說明：採用這種鬆散方式編寫代碼的目的是使代碼更加清晰。
因爲留空格所產生的清晰性是相對的，因此，在已經很是清晰的語句中沒有必要再留空格，若是語句已足夠清晰則括號內側(即左括號後面和右括號前面)不須要加空格，多重括號間沒必要加空格，由於在 C/C++語言中括號已是最清晰的標誌了。在長語句中，若是須要加的空格很是多，那麼應該保持總體清晰，而在局部不加空格。給操做符留空格時不要連續留兩個以上空格。

　　示例：

　　(1) 逗號、分號只在後面加空格。
　　 int a, b, c;

　　(2)比較操做符, 賦值操做符"="、 "+="，算術操做符"+"、 "%"，邏輯操做符"&&"、"&"，位域操做符"<<"、 "^"等雙目操做符的先後加空格。
　　if (current_time >= MAX_TIME_VALUE)
　　a = b + c;
　　a *= 2;
　　a = b ^ 2;

　　(3)"!"、"~"、"++"、"--"、"&"（地址運算符）等單目操做符先後不加空格。
　　flag = !isEmpty;   // 非操做"!"與內容之間
　　p = &mem;     // 地址操做"&" 與內容之間
　　i++;        // "++","--"與內容之間

(4) if、 for、 while、 switch 等與後面的括號間應加空格，使 if 等關鍵字更爲突出、明顯。
if (a >= b && c > d)

3.2 註釋

3.2.1 通常狀況下，源程序有效註釋量必須在20％以上。

　　說明：註釋的原則是有助於對程序的閱讀理解，在該加的地方都加了，註釋不宜太多也不能太少，註釋語言必須準確、易懂、簡潔。

3.2.2 說明性文件（如.java文件）頭部應進行註釋，註釋必須列出：版權說明、版本號、生成日期、做者、內容、功能、與其它文件的關係、修改日誌等，頭文件的註釋中還應有函數功能簡要說明。

　　示例：下面這段頭文件的頭註釋比較標準，固然，並不侷限於此格式，但上述信息建議要包含在內。

　　/*************************************************
　　Copyright (C), 2015-2016, nizwo Tech. Co., Ltd.
　　File name: // 文件名
　　Author: Version: Date: // 做者、版本及完成日期
　　Description: // 用於詳細說明此程序文件完成的主要功能，與其餘模塊
　　// 或函數的接口，輸出值、取值範圍、含義及參數間的控
　　// 制、順序、獨立或依賴等關係
　　Others: // 其它內容的說明
　　Function List: // 主要函數列表，每條記錄應包括函數名及功能簡要說明
　　　　1. ....
　　History: // 修改歷史記錄列表，每條修改記錄應包括修改日期、修改
　　　　　// 者及修改內容簡述
　　1. Date:
　　　Author:
　　 Modification:
　　2. ...
　　*************************************************/

　　說明： Description 一項描述本文件的內容、功能、內部各部分之間的關係及本文件與其它文件關係等。 History 是修改歷史記錄列表，每條修改記錄應包括修改日期、修改者及修改內容簡述。

3.2.3 函數頭部應進行註釋，列出：函數的目的/功能、輸入參數、輸出參數、返回值、調用關係（函數、表）等。

　　示例：下面這段函數的註釋比較標準，固然，並不侷限於此格式，但上述信息建議要包含在內。

　　/*************************************************
　　Function: // 函數名稱
　　Description: // 函數功能、性能等的描述
　　Calls: // 被本函數調用的函數清單
　　Called By: // 調用本函數的函數清單
　　Table Accessed:// 被訪問的表（此項僅對於牽扯到數據庫操做的程序）
　　Table Updated: // 被修改的表（此項僅對於牽扯到數據庫操做的程序）
　　Input: // 輸入參數說明，包括每一個參數的做用、取值說明及參// 數間關係。
　　Output: // 對輸出參數的說明。
　　Return: // 函數返回值的說明
　　Others: // 其它說明
　　*************************************************/

3.2.4 邊寫代碼邊註釋，修改代碼同時修改相應的註釋，以保證註釋與代碼的一致性。再也不有用的註釋要刪除。

3.2.5 註釋的內容要清楚、明瞭，含義準確，防止註釋二義性。

　　說明：錯誤的註釋不但無益反而有害。

3.2.6 避免在註釋中使用縮寫，特別是很是用縮寫。

　　說明：在使用縮寫時或以前，應對縮寫進行必要的說明。

3.2.7 對變量的定義和分支語句（條件分支、循環語句等）必須編寫註釋。

　　說明：這些語句每每是程序實現某一特定功能的關鍵，對於維護人員來講，良好的註釋幫助更好的理解程序，有時甚至優於看設計文檔。

3.2.8 避免在一行代碼或表達式的中間插入註釋。

　　說明：除非必要，不該在代碼或表達中間插入註釋，不然容易使代碼可理解性變差。

3.2.9 註釋格式儘可能統一，建議使用「 /* …… */」，類或方法名註釋使用/**.......*/。

3.2.10 註釋應與其描述的代碼相近，對代碼的註釋應放在其上方或右方（對單條語句的註釋）相鄰位置，不可放在下面，如放於上方則需與其上面的代碼用空行隔開。

　　示例：以下例子不符合規範。

　　例 1：
　　/* get replicate sub system index and net indicator */

　　repssn_ind = ssn_data[index].repssn_index;
　　repssn_ni = ssn_data[index].ni;

　　例 2：
　　repssn_ind = ssn_data[index].repssn_index;
　　repssn_ni = ssn_data[index].ni;
　　/* get replicate sub system index and net indicator */

　　應以下書寫
　　/* get replicate sub system index and net indicator */
　　repssn_ind = ssn_data[index].repssn_index;
　　repssn_ni = ssn_data[index].ni;

3.2.11 將註釋與其上面的代碼用空行隔開。

　　示例：以下例子，顯得代碼過於緊湊。
　　/* code one comments */
　　program code one
　　/* code two comments */
　　program code two

　　應以下書寫
　　/* code one comments */
　　program code one

　　/* code two comments */
　　program code two

3.2.12 註釋與所描述內容進行一樣的縮排。

　　說明：可以使程序排版整齊，並方便註釋的閱讀與理解。

　　示例：以下例子，排版不整齊，閱讀稍感不方便。

　　void example_fun( void )
　　{
　　/* code one comments */
　　CodeBlock One

/* code two comments */
　　CodeBlock Two

　　 }

　　應改成以下佈局。

　　void example_fun( void )
　　{
　　　　/* code one comments */
　　　　CodeBlock One

　　　　/* code two comments */
　　　　CodeBlock Two
　　}

3.2.13 在代碼的功能、意圖層次上進行註釋，提供有用、額外的信息。

　　說明：註釋的目的是解釋代碼的目的、功能和採用的方法，提供代碼之外的信息，幫助讀者理解代碼，防止不必的重複註釋信息。

　　示例：以下注釋意義不大。

　　/* if receive_flag is TRUE */
　　if (receive_flag)

　　而以下的註釋則給出了額外有用的信息。
　　/* if mtp receive a message from links */
　　if (receive_flag)

3.3 變量、結構

3.3.1 去掉不必的公共變量。

　　說明：公共變量是增大模塊間耦合的緣由之一，故應減小不必的公共變量以下降模塊間的耦合度。

3.3.2 仔細定義並明確公共變量的含義、做用、取值範圍及公共變量間的關係。

　　說明：在對變量聲明的同時，應對其含義、做用及取值範圍進行註釋說明，同時如有必要還應說明與其它變量的關係。

3.3.3 當向公共變量傳遞數據時，要十分當心，防止賦與不合理的值或越界等現象發生。

　　說明：對公共變量賦值時，如有必要應進行合法性檢查，以提升代碼的可靠性、穩定性。

3.3.4 防止局部變量與公共變量同名。

　　說明：若使用了較好的命名規則，那麼此問題可自動消除。

3.3.5 嚴禁使用未經初始化的變量做爲右值。

　　說明：引用未經賦值的變量，常常會引發系統崩潰。

3.3.6 結構的設計要儘可能考慮向前兼容和之後的版本升級，併爲某些將來可能的應用保留餘地（如預留一些空間等）。

　　說明：軟件向前兼容的特性，是軟件產品是否成功的重要標誌之一。若是要想使產品具備較好的前向兼容，那麼在產品設計之初就應爲之後版本升級保留必定餘地，而且在產品升級時必須考慮前一版本的各類特性。

3.3.7 編程時，要注意數據類型的強制轉換。

　　說明：當進行數據類型強制轉換時，其數據的意義、轉換後的取值等都有可能發生變化，而這些細節若考慮不周，就頗有可能留下隱患。

3.3.8 儘可能減小沒有必要的數據類型默認轉換與強制轉換。

3.3.9 合理地設計數據並使用自定義數據類型，避免數據間進行沒必要要的類型轉換。

4、XML規範

4.1 佈局

4.1.1 避免過多嵌套

　　說明：嵌套的 LinearLayout 可能會使得 View 的層級結構很深。使用LinearLayout時，一般咱們喜歡用嵌套的佈局來動態設置一個View的Visibility ，因爲LinearLayout是線性的，所以即便隱藏一個View也不會影響到其它View的排列。而在RelativeLayout中，View的位置都是相對於其它View的，所以，隱藏以後，會致使以前的View沒有參考對象了，致使的相對位置改變，這時你可使用 alignWithParentIfMissing=」true」來處理這種狀況。

此外，嵌套使用了 layout_weight 參數的 LinearLayout 的計算量會尤爲大，由於每一個子元素都須要被測量兩次。這對須要屢次重複 inflate 的 Layout 尤爲須要注意，好比使用 ListView 或 GridView 時。

示例：以下佈局

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content">

    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Hello World!"/>
</RelativeLayout>

能夠直接寫成以下佈局

<?xml version="1.0" encoding="utf-8"?>
<TextView xmlns:android="http://schemas.android.com/apk/res/android"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:text="Hello World!"/>