Android 編碼規範

標籤：地方   類常量   ttext   返回   get   版本號碼   參數   產品發布   部分   

編碼規範對於程式員而言，尤為重要，有以下幾個原因：

一個軟體的生命週期中，80%的花費在於維護；

幾乎沒有任何一個軟體，在其整個生命週期中，均由最初的開發來維護；

編碼規範可以改善軟體的可讀性，可以讓程式員儘快而徹底地理解新的代碼；

如果你將源碼作為產品發布，就需要確認它是否被很好的打包並且清晰無誤，一如你已構建的其他任何產品；

命名1．包命名

包名規則：一個唯一的包名的首碼總是全部小寫ASCII字母並且是一個頂級網域名稱，如com、edu、gov、net、org等。包名的後續部分根據不同機構各自內部的命名規範而不盡相同。這類命名規範需要以特定目錄名的組成來區分部門，項目，模組等。

例如：com.issmobile.sina.reader.activity-----------新浪書城項目的Activity包，在客戶不做要求的情況下，盡量按這種格式命名包名。

2．類和介面的命名

命名規則：每個單字首大寫，盡量簡潔而富於描述。使用完整單詞，避免縮寫（除非縮寫已被廣泛使用）。

例如: 

Activity  ------  [xxx]Activity.java   eg：SplashActivity

Dialog   ------  [xxx]Dialog.java      eg：LoginDialog

Service ------- [xxx]Service.java       

常用的工具類--[xxx]Util.java

抽象類別  ------  Abs[xxxx].java

介面      ------  I[xxx].java

3．方法的命名

命名規則：第一個單詞首字母小寫，其後單詞的首字母大寫。

類中常用方法的命名：

類的擷取方法（一般具有傳回值）一般要求在被訪問的欄位名前加上get，如getFirstName()，getLastName()。一般來說，get首碼方法返回的是單個值，find首碼的方法返回的是列表值。

類的設定方法（一般傳回型別為void）：被訪問欄位名的前面加上首碼 set，如setFirstName(),setLastName().

類的布爾型的判斷方法一般要求方法名使用單詞 is或has 做首碼，如isPersistent()，isString()。或者使用具有邏輯意義的單詞，例如equal 或equals。

類的普通方法一般採用完整的英文描述說明成員方法功能，第一個單詞儘可能採用動詞，首字母小寫，如openFile（），addCount（）。

構造方法應該用遞增的方式寫。（參數多的寫在後面）。

toString()方法：一般情況下，每個類都應該定義toString()。

4．變數命名

命名規則：第一個單詞首字母小寫，其後單字首大寫。盡量避免單個字元的變數名，除非是一次性的臨時變數。臨時變數通常被取名為i、j、k，一般用於整型；c、d、e，一般用於字元型。

5．成員變數的命名

命名規則：同變數命名，但不要在私人變數前添加m字樣。

6．常量命名

命名規則：類常量的聲明，應該全部大寫，單詞間用底線隔開。

例如：static final int MIN_WIDTH = 4 ;

      static final int MAX_WIDTH = 999;

7．異常命名

命名規則：自訂異常的命名必須以Exception為結尾，用以明確表示為一個異常。

8．layout命名

命名規則：layout的xml檔案命名必須全部單詞小寫，單詞之間以底線分隔。

例如：activity的布局檔案-------activity_[xxx].xml

         布局檔案引用的檔案-----layout_[xxx].xml

         dialog的布局檔案---------dialog_[xxx].xml

         adapter item      ---------item_[xxx].xml

9．id命名

命名規則：控制項id的命名由控制項名和作用拼成，標識控制項名和作用的第一個單詞首字母小寫，其後單字首大寫，用底線串連（[控制項名]_[作用]）。

例如：editText_userName

      textView_message

      button_login

10．資源命名

命名規則：res中的所有資源（如drawable，string等）命名必須全部單詞小寫，單詞間以底線分隔

注釋

Java程式有兩類注釋：實現注釋(implementation comments)和文檔注釋(document comments)。

實現注釋使用/*...*/ 和 // 。

文檔注釋使用/**...*/,文檔注釋可以通過javadoc工具轉換產生HTML檔案

 

1．檔案注釋

所有源檔案都應該在開頭有一個注釋，其中列出類名、版本資訊、日期和著作權聲明。

/*

* 檔案名稱

* 包含類名列表

* 版本資訊，版本號碼

* 建立日期。

* 著作權聲明

*/

2．類注釋

每一個類都應該包含如下格式的注釋，以說明當前類的功能等

/**

*  類名

*  @author 作者 <br/>

*      實現的主要功能。

*      建立日期

*      修改者，修改日期，修改內容。

*/

3. 方法注釋

每一個方法都應該包含如下格式的注釋，包括當前方法的用途，當前方法參數的含義，當前方法的傳回值的內容和拋出異常的列表。

/**

*

*  方法的一句話概述

*  <p>方法詳述（簡單方法可不必詳述）</p>

*  @params 說明參數含義

*  @return 說明傳回值含義

*  @throws IOException 說明發生此異常的條件

*  @throws NullPointerException 說明發生此異常的條件

*/

4．類成員變數和常量注釋

成員變數和常量要使用java doc形式的注釋說明當前變數或常量的含義。

/**

*  XXXX含義

*/

5．其他注釋

方法內部的注釋如果需要多行使用/*…*/形式，如果單行使用//…形式注釋。方法內部不要使用java doc注釋。

常用規範1．空行

盡量使用空行將邏輯相關程式碼片段分隔開，以提高可讀性

下列情況應該總是使用空行：

a．   一個源檔案的兩個片段(section)之間

b．   類聲明和介面聲明之間

c．    兩個方法之間

d．   方法內的局部變數和方法的第一條語句之間

e．   一個方法內的兩個邏輯段之間，用以提高可讀性

2．方法

一個方法盡量不要超過30行，如果方法太長，說明當前方法商務邏輯已經非常複雜，那麼就需要進行方法拆分，請盡量確保每個方法只作一件事。

3．參數和傳回值

一個方法的參數儘可能的不要超過4個！

如果一個方法返回的是一個錯誤碼，請使用異常！！

儘可能不要使用null， 替代為異常 或者使用空變數 如返回 List 則可以使用Collections.emptyList()

4．神秘的數

代碼中不允許出現單獨的數字，字元！如果需要使用數字或字元，則將它們按照含義封裝為靜態常量！（for語句中除外）

5．控制語句

判斷中如有常量，則應將常量置於判斷式的右側。如：

if ( true == isAdmin())...

盡量不使用三目條件的嵌套。

 

所有if 語句必須用{}包括起來,即便是只有一句：

if (true){

//do something......

}

if (true)

i = 0; //不要使用這種

 

對於迴圈：

盡量避免如下方式

 

while(index < products.getCount()){

//每此都會執行一次getCount()方法，

//若此方法耗時則會影響執行效率

//而且可能帶來同步問題，若有同步需求，請使用同步塊或同步方法

}

推薦方式

 

//將操作結構儲存在臨時變數裡，減少方法調用次數

final int count = products.getCount();

while(index < count){

}

 

6．異常的捕捉處理

通常的思想是只對錯誤採用異常處理：邏輯和編程錯誤，設定錯誤，被破壞的資料，資源耗盡，等等。

通常的法則是系統在正常狀態下以及無重載和硬體失效狀態下，不應產生任何異常。

最小化從一個給定的抽象類別中匯出的異常的個數。對於經常發生的可預計事件不要採用異常。不要使用異常實現控制結構。

若有finally 子句，則不要在try 塊中直接返回，亦不要在finally 中直接返回。

7．存取控制

若沒有足夠理由，不要把執行個體或類變數聲明為公有。通常，執行個體變數無需顯式的設定(set)和擷取(gotten)，通常這作為方法調用的邊緣效應 (side effect)而產生。 

一個具有公有執行個體變數的恰當例子，是類僅作為資料結構，沒有行為。亦即，若你要使用一個結構(struct)而非一個類(如果java 支援結構的話)，那麼把類的執行個體變數聲明為公有是合適的。

8．變數賦值

避免在一個語句中給多個變數賦相同的值。它很難讀懂。例如：

fooBar.fChar = barFoo.lchar = ‘c‘;

不要將賦值運算子用在容易與相等關係運算子混淆的地方。例如：

if (c++ = d++) {        // AVOID! (Java disallows)

      ...

}

應該寫成

if ((c++ = d++) != 0) {

    ...

}

不要使用內嵌(embedded)賦值運算子試圖提高運行時的效率，這是編譯器的工作。例如：

d = (a = b + c) + r;        // AVOID!

應該寫成

a = b + c;

d = a + r;

9．圓括弧

一般而言，在含有多種運算子的運算式中使用圓括弧來避免運算子優先順序問題，是個好方法。

即使運算子的優先順序對你而言可能很清楚，但對其他人未必如此。你不能假設別的程式員和你一樣清楚運算子的優先順序。

if (a == b && c == d)     // AVOID!

if ((a == b) && (c == d))  // RIGHT

10．傳回值

設法讓你的程式結構符合目的。例如：

if (booleanExpression) {

   return true;

} else {

   return false;

}

應該代之以如下方法：

return booleanExpression

 

類似地：

if (condition) {

      return x;

}

return y;

 

應該寫做：

return (condition ? x : y);

11．條件運算子“?”前的運算式

如果一個包含二元運算子的運算式出現在三元運算子" ? : "的"?"之前，那麼應該給運算式添上一對圓括弧。例如：  

(x >= 0) ? x : -x

 

Android 編碼規範