Android編程編碼規范

1. 編程原則

1.1 為方法和類賦予表義性強的名字

為了使代碼更加容易理解，最容易的方法之一是為你的方法賦予表義性強的名字。函數名DoIt、GetIt的可讀性很難CalculateSalesTax、 RetrieveUserID相比。

由縮寫方法名組成的代碼很難理解和維護，沒有理由再這樣做了。

給方法正確的命名，可使程序工程的調試和維護工作大大的改觀。請認真對待方法命名的工作，不要為了減少鍵入操作量而降低方法的可理解度。

實際應用舉例：

1) 給方法命名時應大小寫字母混合使用。如果句子全使用大寫字母，那么閱讀起來就非常困難，而大小寫字母混合使用的句子，閱讀起來就很容易。

2) 定義方法名時不要使用縮寫。如果你認為應用程序中的某些工程應使用縮寫，那么請將這些情況加上注釋，并確保每個人在所有時間內都使用這些縮寫。決不要在某些方法中對某些單詞進行縮寫，而在別的方法中卻不使用縮寫。

1.2 為每個方法賦予單個退出點

1.3 創建方法時，始終都應顯式地定義它的作用域。

1) 如果你真的想創建一個公用方法，請向代碼閱讀者說明這一點。

2) 通過為每個方法賦予一個明確定義的作用域，可以減少代碼閱讀者需要投入的工作量。應確保你為方法賦予最有意義的作用域。如果一個方法只被同一類中的另一個方法調用，那么請將它創建成私有方法。如果該方法是從多個類中的多個方法中調用，請將該說明為公用方法。

1.4 用參數在方法之間傳遞數據

應盡量避免使用類變量。一般來說，變量的作用域越小越好。為了減少類變量，方法之一是將數據作為參數在不同方法之間傳遞，而不是讓方法共享類變量。

1) 為每個參數指定數據類型。

2) 始終要對數進行檢驗，決不要假設你得數據沒有問題。程序員常犯的一個錯誤是在編寫方法時假設數據沒有問題。在初始編程階段，當編寫調用方法時，這樣的假設并無大礙。這時你完全能夠知道什么是參數的許可值，并按要求提供這些值。但如果你不對參數的數據進行檢驗，那么下列情況就會給你帶來很大麻煩：另外某個人創建了一個調用方法，但此人不知道允許的值;你在晚些時候添加了新的調用方法，并錯誤的傳遞了壞數據。

2. 命名約定

第一個字母小寫，中間每個單詞的首寫字母大寫，其它字母小寫，這樣保證了對變量名能夠進行正確的斷句。請避免任何自定義的單詞縮寫，除非此縮寫已經人盡皆知。

2.1 包、類及方法命名

2.2 其它

開發人員如果遇到上述表格中未列舉的類型，請書面通知相關管理人員，由管理人員集中更新列表內容。

3. 使用常量

3.1 使用常量

1. 常數很容易在數據輸入時出錯

常數存在的主要問題之一是你很容易在鍵入數字時出錯，從而顛倒了數字的位置。例如，當你鍵入數字10876時，很容易的鍵入10867或18076。與處理變量和保留字的方法不同，編譯器并不在乎顛倒了位置和不正確的數字，有時簡單的錯誤造成的問題不會立即表現出來，而當問題表現出來時，它們會以隨機的計算錯誤的形式出現，這些錯誤很難準確定位。用常量來取代常數時，編譯器將在編譯時檢查常量的有效性。如果常量不存在，編譯器便將這一情況通知你，并拒絕進行編譯，這可以消除錯誤鍵入的數字帶來的問題，只要常量擁有正確的值，使用該常量的所有代碼也有使用該正確值。

2. 常數很難不斷更新

3. 常量使代碼更容易閱讀

使用常量后，得到的一個額外好處是可使創建的代碼更容易閱讀。常數很不直觀。也許你對常數非常了解，但其他人則根本看不明白。通過合理的給常量命名，使用這些常量的代碼就變得比較直觀了，更容易閱讀。

為常量賦予較寬的作用域，這與使用變量時的情況不同。在一個應用程序中你決不應該兩次創建相同的常量。如果你發現自己復制了一個常量，請將原始的常量說明轉至較寬的作用域，直到該常量可供引用它的所有方法為止。

4. 變量

4.1 定義有焦點的變量

用于多個目的的變量稱為無焦點(多焦點)的變量。無焦點變量所代表的意義與程序的執行流程有關，當程序處于不同位置時，它所表示的意義是不固定的，這樣就給程序的可讀性和可維護性帶來了麻煩。

4.2 只對常用變量名和長變量名進行縮寫

如果需要對變量名進行縮寫時，一定要注意整個代碼中縮寫規則的一致性。例如，如果在代碼的某些區域中使用Cnt，而在另一些區域中又使用Count，就會給代碼增加不必要的復雜性。

變量名中盡量不要出現縮寫。

4.3 使用統一的量詞

通過在結尾處放置一個量詞，就可創建更加統一的變量，它們更容易理解，也更容易搜索。例如，請使用strCustomerFirst和strCustomerLast，而不要使用strFirstCustomer和strLastCustomer。

量詞列表：

4.4 使用肯定形式的布爾變量

給布爾變量命名時，始終都要使用變量的肯定形式，以減少其它開發人員在理解布爾變量所代表的意義時的難度。

4.5 為每個變量選擇最佳的數據類型

這樣即能減少對內存的需求量，加快代碼的執行速度，又會降低出錯的可能性。用于變量的數據類型可能會影響該變量進行計算所產生的結果。在這種情況下，編譯器不會產生運行期錯誤，它只是迫使該值符合數據類型的要求。這類問題極難查找?？偠灾?，請盡量避免隱式轉換。

4.6 盡量縮小變量的作用域

如果變量的作用域大于它應有的范圍，變量可繼續存在，并且在不再需要該變量后的很長時間內仍然占用資源。

它們的主要問題是，任何類中的任何方法都能對它們進行修改，并且很難跟蹤究竟是何處進行修改的。

占用資源是作用域涉及的一個重要問題。對變量來說，盡量縮小作用域將會對應用程序的可靠性產生巨大的影響。

5. 代碼的格式化

5.1 對代碼進行格式化時，要達到的目的

1. 通過代碼分割成功能塊和便于理解的代碼段，使代碼更容易閱讀和理解;

2. 使用空行和注釋行，將程序中邏輯上不相關的代碼塊分開。比如：變量聲明部分和代碼語句間的分隔;較長的方法中，完成不同功能的代碼塊間的分隔。要避免出現邏輯上混亂的分隔，如：某一邏輯功能代碼塊中間用空行進行了分隔，但是在相鄰功能代碼塊之間卻沒有分隔，這樣會給程序閱讀者造成錯覺。

3. 減少為理解代碼結構而需要做的工作;

4. 使代碼的閱讀者不必進行假設;

5. 使代碼結構盡可能做到格式清楚明了。

5.2 編程原則

1. 不要將多個語句放在同一行上

不論是變量聲明，還是語句都不要在一行上書寫多個。

2. 在if語句后縮進;

在else語句后縮進

在switch語句后縮進

在case語句后縮進

在do句后縮進

已經用行接續符分割的語句的各個行要縮進

對從屬于行標注的代碼進行縮進。

. 在執行統一任務的各個語句組之間插入一個空行。好的代碼應由按邏輯順序排列的進程或相關語句組構成。

6. 代碼的注釋

6.1 使用代碼注釋的目的

1. 文字說明代碼的作用(即為什么要用編寫該代碼,而不是如何編寫);

2. 確指出該代碼的編寫思路和邏輯方法;

3. 人們注意到代碼中的重要轉折點;

4. 使代碼的閱讀者不必在他們的頭腦中仿真運行代碼的執行方法.

6.2 編程原則

1. 用文字說明代碼的作用:

簡單的重復代碼做寫什么,這樣的注釋幾乎不能給注釋增加什么信息.如果你使用好的命名方法來創建直觀明了的代碼那么這些類型的注釋絕對增加不了什么信息.

2. 如果你想違背好的編程原則,請說明為什么

有的時候你可能需要違背好的編程原則，或者使用了某些不正規的方法.遇到這種情況時,請用內部注釋來說明你在做什么和為什么要這樣做。

技巧性特別高的代碼段，一定要加詳細的注釋，不要讓其他開發人員花很長時間來研究一個高技巧但不易理解的程序段。

3. 用注釋來說明何時可能出錯和為什么出錯

4. 在編寫代碼前進行注釋

給代碼加注釋的方法之一是在編寫一個方法前首先寫上注釋.如果你愿意,可以編寫完整句子的注釋或偽代碼.一旦你用注釋對代碼進行了概述,就可以在注釋之間編寫代碼.

5. 在要注釋的代碼前書寫注釋

注釋一定出現在要注釋的程序段前，不要在某段程序后書寫對這段程序的注釋，先看到注釋對程序的理解會有一定幫助。

如果有可能，請在注釋行與上面代碼間加一空行。

6. 純色字符注釋行只用于主要注釋

注釋中要分隔時，請使用一行空注釋行來完成，不要使用純色字符，以保持版面的整潔、清晰。

7. 避免形成注釋框

用星號圍成的注釋框，右邊的星號看起來很好,但它們給注釋增加了任何信息嗎?實際上這會給編寫或編輯注釋的人增加許多工作。

8. 增強注釋的可讀性

注釋是供人閱讀的，而不是讓計算機閱讀的。

1) 使用完整的語句。雖然不必將注釋分成段落(最好也不要分成段落)，但你應盡量將注釋寫成完整的句子。

2) 避免使用縮寫?？s寫常使注釋更難閱讀，人們常用不同的方法對相同的單詞進行縮寫，這會造成許多混亂，如果必須對詞匯縮寫，必須做到統一。

3) 將整個單詞大寫，以突出它們的重要性。若要使人們注意注釋中的一個或多個單詞，請全部使用大寫字母。(此處限于英文注釋)

9. 對注釋進行縮進，使之與后隨的語句對齊。

注釋通常位于它們要說明的代碼的前面。為了從視覺上突出注釋與它的代碼之間的關系，請將注釋縮進，使之與代碼處于同一個層次上。

10. 為每個方法賦予一個注釋標頭

每個方法都應有一個注釋標頭。方法的注釋標頭可包含多個文字項，比如輸入參數、返回值、原始作者、最后編輯該方法的程序員、上次修改日期、版權信息。

11. 當行尾注釋用在上面這種代碼段結構中時，它們會使代碼更難閱讀。

使用多個行尾注釋時(比如用于方法頂部的多個變量說明)，應使它們互相對齊。這可使它們稍容易閱讀一些。

12. 何時書寫注釋

1) 請在每個if語句的前面加上注釋。

2) 在每個switch語句的前面加上注釋。與if語句一樣，switch語句用于評估對程序執行產生影響的表達式。

3) 在每個循環的前面加上注釋。每個循環都有它的作用，許多情況下這個作用不清楚直觀。

6.3 注釋那些部分

6.4 示例

6.4.1 塊注釋：

主要用來描述文件，類，方法，算法等。一般用在文檔和方法的前面，也可以放在文檔的任何地方。以‘/*’開頭，‘*/’結尾。例：

……

/*

* 注釋

*/

……

6.4.2 行注釋：

主要用在方法內部，對代碼，變量，流程等進行說明。與塊注釋格式相似，但是整個注釋占據一行。例：

……

/* 注釋 */

……

6.4.3 尾隨注釋：

與行注釋功能相似，放在代碼的同行，但是要與代碼之間有足夠的空間，便于分清。例：

int m=4 ; /* 注釋 */

如果一個程序塊內有多個尾隨注釋，每個注釋的縮進應該保持一致。

6.4.4 行尾注釋：

與行注釋功能相似，放在每行的最后，或者占據一行。以‘//’開頭。

6.4.5 文檔注釋：

與塊注釋相似，但是可以被javadoc處理，生成HTML文件。以‘/**’開頭，‘*/’結尾。文檔注釋不能放在方法或程序塊內。例：

/**

注釋

*/

7. 表達式和語句

7.1 每行應該只有一條語句。

7.2 if-else,if-elseif語句，任何情況下，都應該有“{”，“}”，格式如下：

if (condition)

{

statements;

}

else if (condition)

{

statements;

}

Else

{

statements;

}

7.3 for語句格式如下：

for (initialization; condition; update)

{

statements;

}

如果語句為空：

for (initialization; condition; update) ;

7.4 while語句格式如下：

while (condition)

{

statements;

}

如果語句為空:

while (condition);

7.5 do-while語句格式如下：

do

{

statements;

} while (condition);

7.6 switch語句，每個switch里都應包含default子語句,格式如下：

switch (condition)

{

case ABC:

statements;

/* falls through */

case DEF:

statements;

break;

case XYZ:

statements;

break;

default:

statements;

break;

}

7.7 try-catch語句格式如下：

try {

statements;

} catch (ExceptionClass e) {

statements;

} finally {

statements;

}

8. 調試方法

程序中應該有足夠的調試信息，一般來講調試信息必須指明此信息是在哪個文件、哪個方法、哪一行輸出的。調試信息的文字描述不應采用縮寫的方式，應當盡可能的描述清楚此調試信息的目的。如以下過于簡短的調試信息：

Log.d(“xx”,”count is ”+count);

count指的是什么的計數呢?這就導致了模糊不清，降低了代碼調試的效率。

以android常用的調試類Log為例，舉個例子。

每個源文件中定義一個String 常量THIS，用來描述此文件名

private static final String THIS = ”PalmmessagerService”;

在需要輸出調試信息的地方調用Log方法。注意，對于不同的情況請選擇最合適的Log方法!如，在出現錯誤的地方調用Log.e

Log.e(THIS,”+++ error!there is something wrong! +++”);

而一般情況下調用Log.d。如

Log.d(THIS,”+++ I have an apple +++”);

如同一個文件內，在不同的地方出現同樣的調試信息，請寫明各調試信息是在哪個方法中輸出的。如：

Log.d(THIS,”+++ funca I have an apple +++”);

Log.d(THIS,”+++ funcb I have an apple +++”);