ND_Android編程規(guī)范(JAVA).docx

文檔名稱無線事業(yè)部-Android開發(fā)小組-Java編碼規(guī)范文檔編號ND_Android_Java_Code_Conventions版本號1.00無線事業(yè)部（Android開發(fā)小組）Java編碼規(guī)范福建省網(wǎng)龍中國有限公司 版權所有 版 本 歷 史版本/狀態(tài)作者參與者日期備注審核人審核時間v0.1/草稿王明禮V1.0/正式趙敬雙200-4-15V1.2/修訂王明禮2009-4-27 目 錄1.介紹(INTRODUCTION)51.1.為什么要有編碼規(guī)范(Why Have Code Conventions)51.2.版權聲明(Acknowledgments)52.文件名(FILE NAMES)52.1.文件后綴(File Suffixes)52.2.常用文件名(Common File Names)53.文件組織(FILE ORGANIZATION)63.1.Java源文件(Java Source Files)63.1.1.開頭注釋(Beginning Comments)63.1.2.包和引入語句(Package and Import Statements)63.1.3.類和接口聲明(Class and Interface Declarations)74.縮進排版(INDENTATION)74.1.行長度(Line Length)74.2.換行(Wrapping Lines)75.注釋(COMMENTS)95.1.實現(xiàn)注釋的格式(Implementation Comment Formats)105.1.1.塊注釋(Block Comments)105.1.2.單行注釋(Single-Line Comments)105.1.3.尾端注釋(Trailing Comments)105.1.4.行末注釋(End-Of-Line Comments)115.1.5.修改記錄注釋（Change History Comments）115.2.文檔注釋(Documentation Comments)136.聲明(DECLARATIONS)146.1.每行聲明變量的數(shù)量(Number Per Line)146.2.初始化(Initialization)146.3.布局(Placement)146.4.類和接口的聲明(Class and Interface Declarations)157.語句(STATEMENTS)167.1.簡單語句(Simple Statements)167.2.復合語句(Compound Statements)167.3.返回語句(return Statements)167.4.if-else，if-else，if else-if else語句(if, if-else, if else-if else Statements)167.5.for語句(for Statements)177.6.while語句(while Statements)177.7.do-while語句(do-while Statements)187.8.switch語句(switch Statements)187.9.try-catch語句(try-catch Statements)188.空白(WHITE SPACE)198.1.空行(Blank Lines)198.2.空格(Blank Spaces)199.命名規(guī)范(NAMING CONVENTIONS)2010.編程慣例(PROGRAMMING PRACTICES)2110.1.提供對實例以及類變量的訪問控制(Providing Access to Instance and Class Variables)2110.2.引用類變量和類方法(Referring to Class Variables and Methods)2110.3.常量(Constants)2210.4.變量賦值(Variable Assignments)2210.5.其它慣例(Miscellaneous Practices)2210.5.1.圓括號(Parentheses)2210.5.2.返回值(Returning Values)2310.5.3.條件運算符?前的表達式(Expressions before ? in the Conditional Operator)2310.5.4.特殊注釋(Special Comments)2310.5.5.重寫equals 時一定要重寫hashCode2310.5.6.禁止內部賦值語句2310.5.7.long 類型常量以大寫L結尾。2410.5.8.只有static方法的類，2410.5.9.信令類2411.代碼范例(CODE EXAMPLES)2411.1.Java源文件范例(Java Source File Example)24 1. 介紹(Introduction)1.1. 為什么要有編碼規(guī)范(Why Have Code Conventions)編碼規(guī)范對于程序員很是重要，有以下幾個原因： 一個軟件的生命周期中，80%的花費用于維護 幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護 編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼，特別是當我們去維護或使用別人的源代碼時，進而可提高工作效率1.2. 版權聲明(Acknowledgments)本文檔為網(wǎng)龍公司無線事業(yè)部Android應用軟件開發(fā)組所有。2. 文件名(File Names)這部分列出了常用的文件名及其后綴。2.1. 文件后綴(File Suffixes)Java程序使用下列文件后綴：文件類別文件后綴Java源文件.javaAIDL接口文件.aidlJava字節(jié)碼文件.class2.2. 常用文件名(Common File Names)常用的文件名包括： 文件名用途MakeFilemakefile 的文件名。我們采用 gnumake來創(chuàng)建（build）軟件。README概述特定目錄下所含文件的內容3. 文件組織(File Organization)一個文件由被空行分割而成的段落以及標識每個段落的可選注釋共同組成。超過2000行的程序難以閱讀，應該予以避免。Java源文件范例提供了一個布局合理的Java程序范例。3.1. Java源文件(Java Source Files)每個Java源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關聯(lián)，可以將它們和公共類放入同一個源文件。公共類必須是這個文件中的第一個類或接口。Java源文件還遵循以下規(guī)則： 包和引入語句 類和接口聲明3.1.1. 包和引入語句(Package and Import Statements)在多數(shù)Java源文件中，第一個非注釋行是包語句。在它之后可以跟引入語句。Package 的名字應該都是由一個小寫單詞組成， 例如：package java.awt;import java.awt.peer.canvapeer;包引入時避免無用的引入，如：java.lang文件夾下的類，java.lang.Object;3.1.2. 類和接口聲明(Class and Interface Declarations)下表描述了類和接口聲明的各個部分以及它們出現(xiàn)的先后次序。類/接口聲明的各部分說明1類/接口文檔注釋(/*/)類和接口應該有標準Javadoc注釋2類或接口的聲明類名和接口的第一個字符大寫，每個單詞的首字母大寫，中間可以有下劃線3類/接口實現(xiàn)的長度限制限制一個匿名內部類的長度不要超過80行 4類的(靜態(tài))變量首先是類的公共變量，隨后是保護變量，再后是包一級別的變量(沒有訪問修飾符，access modifier)，最后是私有變量。靜態(tài)final變量應全部大寫，中間可以有下劃線5實例變量首先是公共級別的，隨后是保護級別的，再后是包一級別的(沒有訪問修飾符)，最后是私有級別的。實例變量首字母小寫，其后每個單詞的首字母大寫或以下劃線分割6構造器構造器的代碼長度（不計空行），不應超過200行7方法方法名應為動詞或動賓短語，首字母小寫，其后每個單詞首字母大寫或以下劃線分割，限制一個類方法的長度不要超過600行，方法的參數(shù)不要超過8個,參數(shù)名字必須和變量的命名規(guī)范一致,public 的方法之前應該有Javadoc注釋，方法之后的大括號位于行尾4. 縮進排版(Indentation)4個空格常被作為縮進排版的一個單位。4.1. 行長度(Line Length)避免一行的長度超過120個字符，因為很多終端和工具不能很好處理之。如果有尾注釋的行，應該根據(jù)尾注釋的長度，選擇更短的行長。4.2. 換行(Wrapping Lines)當一個表達式無法容納在一行內時，可以依據(jù)如下一般規(guī)則斷開之： 在一個逗號后面斷開 在一個操作符前面斷開 選擇較高級別(higher-level)的斷開，而非較低級別(lower-level)的斷開 新的一行應該與上一行同一級別表達式的開頭處對齊 如果以上規(guī)則導致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進8個空格。 以下是斷開方法調用的一些例子：someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 以下是兩個斷開算術表達式的例子。前者更好，因為斷開處位于括號表達式的外邊，這是個較高級別的斷開。longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /PREFFERlongName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /AVOID 以下是兩個縮進方法聲明的例子。前者是常規(guī)情形。后者若使用常規(guī)的縮進方式將會使第二行和第三行移得很靠右，所以代之以縮進8個空格/CONVENTIONAL INDENTATIONsomeMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) ./INDENT 8 SPACES TO AVOID VERY DEEP INDENTSprivate static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . if語句的換行通常使用8個空格的規(guī)則，因為常規(guī)縮進(4個空格)會使語句體看起來比較費勁。比如：/DONT USE THIS INDENTATIONif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS/USE THIS INDENTATION INSTEADif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt();/OR USE THISif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); 這里有三種可行的方法用于處理三元運算表達式：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta : gamma; 5. 注釋(Comments)Java程序有兩類注釋：實現(xiàn)注釋(implementation comments)和文檔注釋(document comments)。實現(xiàn)注釋是那些在C+中見過的，使用/*.*/和/界定的注釋。文檔注釋(被稱為doc comments)是Java獨有的，并由/*.*/界定。文檔注釋可以通過javadoc工具轉換成HTML文件。實現(xiàn)注釋用以注釋代碼或者實現(xiàn)細節(jié)。文檔注釋從實現(xiàn)自由(implementation -free)的角度描述代碼的規(guī)范。它可以被那些手頭沒有源碼的開發(fā)人員讀懂。注釋應被用來給出代碼的總括，并提供代碼自身沒有提供的附加信息。注釋應該僅包含與閱讀和理解程序有關的信息。例如，相應的包如何被建立或位于哪個目錄下之類的信息不應包括在注釋中。在注釋里，對設計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應避免提供代碼中己清晰表達出來的重復信息。多余的的注釋很容易過時。通常應避免那些代碼更新就可能過時的注釋。注意：頻繁的注釋有時反映出代碼的低質量。當你覺得被迫要加注釋的時候，考慮一下重寫代碼使其更清晰。注釋不應寫在用星號或其他字符畫出來的大框里。注釋不應包括諸如制表符和回退符之類的特殊字符。5.1. 實現(xiàn)注釋的格式(Implementation Comment Formats)程序可以有4種實現(xiàn)注釋的風格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。5.1.1. 塊注釋(Block Comments)塊注釋通常用于提供對文件，方法，數(shù)據(jù)結構和算法的描述。塊注釋被置于每個文件的開始處以及每個方法之前。它們也可以被用于其他地方，比如方法內部。在功能和方法內部的塊注釋應該和它們所描述的代碼具有一樣的縮進格式。我們要求對于自定義的邏輯復雜的方法，有同步和其他互操作的方法一定要加以注釋。塊注釋之首應該有一個空行，用于把塊注釋和代碼分割開來，比如： /* * Here is a block comment. */5.1.2. 單行注釋(Single-Line Comments)短注釋可以顯示在一行內，并與其后的代碼具有一樣的縮進層級。如果一個注釋不能在一行內寫完，就該采用塊注釋。單行注釋之前應該有一個空行。以下是一個Java代碼中單行注釋的例子： if (condition) /* Handle the condition. */ . 5.1.3. 尾端注釋(Trailing Comments)極短的注釋可以與它們所要描述的代碼位于同一行，但是應該有足夠的空白來分開代碼和注釋。若有多個短注釋出現(xiàn)于大段代碼中，它們應該具有相同的縮進。以下是一個Java代碼中尾端注釋的例子： if (a = 2) return TRUE; /* special case */ else return isPrime(a); /* works only for odd a */ 5.1.4. 行末注釋(End-Of-Line Comments)注釋界定符/，可以注釋掉整行或者一行中的一部分。它一般不用于連續(xù)多行的注釋文本；然而，它可以用來注釋掉連續(xù)多行的代碼段。以下是所有三種風格的例子： if (foo 1) / Do a double-flip. . else return false; / Explain why here. /if (bar 1) / / / Do a triple-flip. / . / /else / return false; /5.1.5. 修改記錄注釋（Change History Comments）文件頭修改記錄部分記錄了代碼中的修改歷史，為了表示的方便，這里分為單行注釋和多行注釋。Tracking Number在版本發(fā)布前可以是順序數(shù)字號（只要保證唯一即可），在發(fā)布版本后需要試用Bug號標示。單行注釋參考下面“#00001”部分，多行注釋參考下面“#00002”部分，注釋部分采用了一些特殊符號來傳達一些特殊的含義。增加內容用“+”號表示，刪除注釋用“-”號表示，注釋開始用“-”表示，注釋結束用“/ /* instanceVar1 documentation comment */ public Object o_instanceVar1; / /* instanceVar2 documentation comment */ protected int i_instanceVar2; / /* instanceVar3 documentation comment */ int i_instanceVar2;/ /* instanceVar4 documentation comment */ private Object ao_instanceVar3;/ #00002 - /* instanceVar5 documentation comment */ protected int i_instanceVar5; /* instanceVar6 documentation comment */ int i_instanceVar6;/ #00002 + / /*/ * .method doSomething documentation comment./ */ public void doSomething() / / / .implementation goes here./ / #00002 - /* * .method doNewSomething documentation comment. */ public void doNewSomething() / .implementation goes here. / #00002 + - 5.2. 文檔注釋(Documentation Comments)注意：此處描述的注釋格式之范例，參見java源文件范例若想了解更多有關文檔注釋和javadoc的詳細資料，參見javadoc的主頁：/javadoc/index.html文檔注釋描述Java的類、接口、構造器，方法，以及字段(field)。每個文檔注釋都會被置于注釋定界符/*.*/之中，一個注釋對應一個類、接口或成員。該注釋應位于聲明之前： /* * The Example class provides . */ public class Example . 注意頂層(top-level)的類和接口是不縮進的，而其成員是縮進的。描述類和接口的文檔注釋的第一行(/*)不需縮進；隨后的文檔注釋每行都縮進1格(使星號縱向對齊)。成員，包括構造函數(shù)在內，其文檔注釋的第一行縮進4格，隨后每行都縮進5格。文檔注釋不能放在一個方法或構造器的定義塊中，因為Java會將位于文檔注釋之后的第一個聲明與其相關聯(lián)。6. 聲明(Declarations)6.1. 每行聲明變量的數(shù)量(Number Per Line)推薦一行一個聲明，因為這樣便于寫注釋。亦即， int level; / indentation level int size; / size of table要優(yōu)于， int level, size; Long類型的變量后應跟L，float類型變量后面應跟f不要將不同類型變量的聲明放在同一行，例如： int foo, fooarray; /WRONG!注意：上面的例子中，在類型和標識符之間放了一個空格，另一種被允許的替代方式是使用制表符： intlevel; / indentation level intsize; / size of table ObjectcurrentEntry; / currently selected table entry6.2. 初始化(Initialization)盡量在聲明局部變量的同時初始化。唯一不這么做的理由是變量的初始值依賴于某些先前發(fā)生的計算。如：String name = null;6.3. 布局(Placement) 盡量只在代碼塊的開始處聲明變量。（一個塊是指任何被包含在大括號和中間的代碼。）不要在首次用到該變量時才聲明之。這會把注意力不集中的程序員搞糊涂，同時會妨礙代碼在該作用域內的可移植性。 void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 該規(guī)則的一個例外是for循環(huán)的索引變量 for (int i = 0; i = 0) ? x : -x; 10.5.3. 特殊注釋(Special Comments)在注釋中使用XXX來標識某些未實現(xiàn)(bogus)的但可以工作(works)的內容。用FIXME來標識某些假的和錯誤的內容。10.5.4. 重寫equals 時一定要重寫hashCode10.5.5. long 類型常量以大寫L結尾。10.5.6. 只有static方法的類，構造函數(shù)應為private ,在此不做強制要求，但應該注意。10.5.7. 信令類如果類只是用來作為信息傳遞的中間變量，則應該聲明為信令類，即所有的全局變量都是final類型，在初始化時賦值 如：private final String name;public Foo(String str)name = str;避免在構造函數(shù)中出現(xiàn)this引用，如：public Foo(String str )this.str = str; /避免10.5.8. 修飾符順序修飾符的順序應為 ：public-protected-p