Java編碼規(guī)范V10

1、Java 編碼規(guī)范文件更改摘要：日期版本號修訂說明修訂人審核人批準(zhǔn)人目 錄1. 介紹41.1 為什么要有編碼規(guī)范41.2 注意事項42. 文件名42.1 文件后綴42.2 常用文件名43. 文件組織53.1 Java源文件53.1.1 包和引入語句53.1.2 類和接口聲明54. 縮進排版64.1 行長度64.2 換行64.3 對于85. 注釋85.1 實現(xiàn)注釋的格式85.1.1 塊注釋85.1.2 單行注釋95.1.3 尾端注釋95.1.4 行末注釋95.2 文檔注釋105.3 注釋內(nèi)容105.3.1 方法注釋105.3.2 算法注釋11可精簡的注釋內(nèi)容11推薦的注釋內(nèi)容115.3.5 Nu

2、ll的規(guī)約11 特殊代碼注釋126. 聲明126.1 每行聲明變量的數(shù)量126.2 初始化126.3 布局126.4 類和接口的聲明136.5 聲明規(guī)則147. 語句147.1 簡單語句147.2 復(fù)合語句147.3 返回語句147.4 if，if-else，if else-if else語句157.5 for語句157.6 while語句167.7 do-while語句167.8 switch語句167.9 try-catch語句168. 空白178.1 空行178.2 空格179. 命名規(guī)范189.1 命名規(guī)則199.1.1 包命名199.1.2 類、接口命名19方法命名19變量命名20常

3、量命名2010. 編程慣例2010.1 提供對實例以及類變量的訪問控制2010.2 引用類變量和類方法2010.3 常量2010.4 變量賦值2110.5 異常處理2110.6 其它慣例2110.6.1 圓括號2110.6.2 返回值2110.6.3 條件運算符“?”前的表達(dá)式*2211. 信息輸出2212. 代碼范例2212.1 Java源文件范例221. 介紹1.1 為什么要有編碼規(guī)范編碼規(guī)范對于程序員而言尤為重要，有以下幾個原因：l 一個軟件的生命周期中，80%的花費在于維護；l 幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護；l 編碼規(guī)范可以改善軟件的可讀性，可以讓

4、程序員盡快而徹底地理解新的代碼；l 如果你將源碼作為產(chǎn)品發(fā)布，就需要確任它是否被很好的打包并且清晰無誤，一如你已構(gòu)建的其它任何產(chǎn)品。制定本規(guī)范的目的是為了讓代碼清晰整潔、增強可讀性。所有編碼必須圍繞此原則，即使是本規(guī)范中未特別指明1.2 注意事項l 本文檔未特別標(biāo)注的都必須遵守(不遵守將代表代碼不合格，會給團隊其他成員帶來不便和困擾，大大提高總體維護成本)2. 文件名這部分列出了常用的文件名及其后綴。2.1 文件后綴Java程序使用下列文件后綴：文件類別文件后綴Java源文件.javaJava字節(jié)碼文件.classJSP文件.jspXML文件.xml資源文件.properties日志文件.lo

5、gTag lib文件.tldJava 包文件.jar層疊樣式表文件.css2.2 常用文件名常用的文件名包括：文件名用途Build.xmlAnt 編譯配置Web.xmlJava Web程序的配置文件Server.xmlTomcat的配置文件pertiesLog4j配置文件Hibernate配置文件ApplicationRperties程序的英文資源文件ApplicationResources_zh_CN.properties程序的gbk資源文件struts-config-*.xmlStruts配置文件applicationContext-*.xmlSp

6、ring配置文件3. 文件組織一個文件由被空行分割而成的段落以及標(biāo)識每個段落的可選注釋共同組成。超過2000行的程序難以閱讀，應(yīng)該盡量避免。“Java源文件范例”提供了一個布局合理的Java程序范例。3.1 Java源文件每個Java源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關(guān)聯(lián)，可以將它們和公共類放入同一個源文件。公共類必須是這個文件中的第一個類或接口。Java源文件還遵循以下規(guī)則： 包和引入語句 類和接口聲明3.1.1 包和引入語句在Java源文件中，第一個非注釋行是包語句。在它之后可以跟引入語句。例如：package java.awt;import java.awt

7、.peer.CanvasPeer;import 順序：系統(tǒng)，第三方，自定義3.1.2 類和接口聲明下表描述了類和接口聲明的各個部分以及它們出現(xiàn)的先后次序。參見代碼范例類/接口聲明的各部分注釋1類/接口文檔注釋(/*/)該注釋中所需包含的信息，參見“文檔注釋”2類或接口的聲明3類/接口實現(xiàn)的注釋(/*/)如果有必要的話該注釋應(yīng)包含任何有關(guān)整個類或接口的信息，而這些信息又不適合作為類/接口文檔注釋。4類的（靜態(tài)）變量首先是類的公共變量，隨后是保護變量，再后是包一級別的變量（沒有訪問修飾符），最后是私有變量。5實例變量首先是公共級別的，隨后是保護級別的，再后是包一級別的（沒有訪問修飾符），最后是私有

8、級別的。6構(gòu)造器7方法這些方法應(yīng)該按功能，而非作用域或訪問權(quán)限，分組。例如，一個私有的類方法可以置于兩個公有的實例方法之間。其目的是為了更便于閱讀和理解代碼。（實現(xiàn)同一功能的多個方法應(yīng)放在一起）4. 縮進排版對于用eclipse開發(fā)的項目，每個java源文件，必須使用eclipse工具中自帶的排版組合鍵 ctrl+shift+F4個空格常被作為縮進排版的一個單位。將制表符設(shè)為4個空格 。4.1 行長度盡量避免一行的長度超過80個字符，因為很多終端和工具不能很好處理。注意：用于文檔中的例子應(yīng)該使用更短的行長，長度一般不超過70個字符。4.2 換行當(dāng)一個表達(dá)式無法容納在一行內(nèi)時，可以依據(jù)如下一般規(guī)

9、則斷開：l 在一個逗號后面斷開；l 在一個操作符前面斷開；l 寧可選擇較高級別(higher-level)的斷開，而非較低級別(lower-level)的斷開；l 新的一行應(yīng)該與上一行同一級別表達(dá)式的開頭處對齊；l 如果以上規(guī)則導(dǎo)致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進8個空格。以下是斷開方法調(diào)用的一些例子：someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);var = someMethod1(longExpression1, someMe

10、thod2(longExpression2, longExpression3);以下是兩個斷開算術(shù)表達(dá)式的例子。前者更好，因為斷開處位于括號表達(dá)式的外邊，這是個較高級別的斷開。longName1 = longName2 * (longName3 + longName4 - longName5)+ 4 * longname6; /PREFFERlongName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /AVOID以下是兩個縮進方法聲明的例子。前者是常規(guī)情形，后者若使用常規(guī)的縮進方式將會使第二行和第三行

11、移得很靠右，所以代之以縮進8個空格。/CONVENTIONAL INDENTATION someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . /INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnothe

12、r) .if語句的換行通常使用8個空格的規(guī)則，因為常規(guī)縮進(4個空格)會使語句體看起來比較費勁。比如：/DONT USE THIS INDENTATION if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS /USE THIS INDENTATION INSTEAD if (condition1 & condition2) | (condition3 &

13、condition4) |!(condition5 & condition6) doSomethingAboutIt(); /OR USE THIS if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); 這里有三種可行的方法用于處理三元運算表達(dá)式： alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamm

14、a; alpha = (aLongBooleanExpression) ? beta : gamma;4.3 對于if,for,while語句只有單句時，如果該句可能引起閱讀混淆，需要用 和括起來。/錯誤，需要使用花括號括起來if (condition) if(condition) doSomething();else doSomething();5. 注釋Java程序有兩類注釋：實現(xiàn)注釋(implementation comments)和文檔注釋(document comments)。實現(xiàn)注釋是那些在C+中見過的，使用/*.*/和/界定的注釋。文檔注釋(被稱為doc comments)是Ja

15、va獨有的，并由/*.*/界定。文檔注釋可以通過javadoc工具轉(zhuǎn)換成HTML文件。實現(xiàn)注釋用以注釋代碼或者實現(xiàn)細(xì)節(jié)。文檔注釋從實現(xiàn)自由(implementation-free)的角度描述代碼的規(guī)范。它可以被那些手頭沒有源碼的開發(fā)人員讀懂。注釋應(yīng)被用來給出代碼的總括，并提供代碼自身沒有提供的附加信息。注釋應(yīng)該僅包含與閱讀和理解程序有關(guān)的信息。例如，相應(yīng)的包如何被建立或位于哪個目錄下之類的信息不應(yīng)包括在注釋中。在注釋里，對設(shè)計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應(yīng)避免提供代碼中己清晰表達(dá)出來的重復(fù)信息。多余的注釋很容易過時。通常應(yīng)避免那些代碼更新就可能過時的注釋。注意：頻繁的

16、注釋有時反映出代碼的低質(zhì)量。當(dāng)你覺得被迫要加注釋的時候，考慮一下重寫代碼使其更清晰。注釋不應(yīng)寫在用星號或其他字符畫出來的大框里。注釋不應(yīng)包括諸如制表符和回退符之類的特殊字符。5.1 實現(xiàn)注釋的格式程序可以有4種實現(xiàn)注釋的風(fēng)格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。 塊注釋塊注釋通常用于提供對文件，方法，數(shù)據(jù)結(jié)構(gòu)和算法的描述。塊注釋被置于每個文件的開始處以及每個方法之前。它們也可以被用于其他地方，比如方法內(nèi)部。在功能和方法內(nèi)部的塊注釋應(yīng)該和它們所描述的代碼具有一樣的縮進格式。塊注釋之首應(yīng)該有一個空行，用于把塊注釋和代碼分割開來

17、，比如：/* * Here is a block comment. */塊注釋可以以/*-開頭，這樣indent(1)就可以將之識別為一個代碼塊的開始，而不會重排它。 /*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */注意：如果你不使用indent(1)，就不必在代碼中使用/*-，或為他人可能對你的代碼運行indent(1)作讓步。 單行注釋短注釋可以顯示在一行內(nèi)，并與其后的代碼具有一樣的縮進層級。如

18、果一個注釋不能在一行內(nèi)寫完，就該采用塊注釋。單行注釋之前應(yīng)該有一個空行。以下是一個Java代碼中單行注釋的例子： if (condition) /* Handle the condition. */. 尾端注釋極短的注釋可以與它們所要描述的代碼位于同一行，但是應(yīng)該有足夠的空白來分開代碼和注釋。若有多個短注釋出現(xiàn)于大段代碼中，它們應(yīng)該具有相同的縮進。以下是一個Java代碼中尾端注釋的例子： if (a = 2) return true; /* special case */ else return isPrime(a); /* works only for odd a */ 行末注釋注釋界定符“

19、/”，可以注釋掉整行或者一行中的一部分。它一般不用于連續(xù)多行的注釋文本；然而，它可以用來注釋掉連續(xù)多行的代碼段。以下是所有三種風(fēng)格的例子： if (foo 1) / Do a double-flip. . else return false; / Explain why here. /if (bar 1) / / Do a triple-flip. / . / else / return false; /5.2 文檔注釋文檔注釋描述Java的類、接口、構(gòu)造器，方法，以及字段(field)。每個文檔注釋都會被置于注釋定界符/*.*/之中，一個注釋對應(yīng)一個類、接口或成員。該注釋應(yīng)位于聲明之前： /

20、* * The Example class provides . */ public class Example .注意頂層(top-level)的類和接口是不縮進的，而其成員是縮進的。描述類和接口的文檔注釋的第一行(/*)不需縮進；隨后的文檔注釋每行都縮進1格(使星號縱向?qū)R)。成員，包括構(gòu)造函數(shù)在內(nèi)，其文檔注釋的第一行縮進4格，隨后每行都縮進5格。若你想給出有關(guān)類、接口、變量或方法的信息，而這些信息又不適合寫在文檔中，則可使用實現(xiàn)塊注釋(見)或緊跟在聲明后面的單行注釋(見5.1.2)。例如，有關(guān)一個類實現(xiàn)的細(xì)節(jié)，應(yīng)放入緊跟在類聲明后面的實現(xiàn)塊注釋中，而不是放在文檔注釋中。文檔注釋不能放在一

21、個方法或構(gòu)造器的定義塊中，因為Java會將位于文檔注釋之后的第一個聲明與其相關(guān)聯(lián)。5.3 注釋內(nèi)容5.3.1 方法注釋為了讓別人能夠很快看懂該方法。方法注釋語包括一下幾部分：l 方法的描述:該方法有什么作用l 參數(shù)介紹（可選，有參數(shù)必須注釋）l 方法返回值（可選，有返回值必須注釋）l 是否拋出異常（可選，有異常必須注釋）l 作者（可選，當(dāng)該方法不是當(dāng)前文件的創(chuàng)建者需要注釋）范例如下:/* * 把指定的SessionBean部署到Mock的容器環(huán)境中。 * * param jndi JNDI名稱 * param home 主接口 * param remote 遠(yuǎn)程接口* param bean 實

22、現(xiàn)類* return void * throws Exception * author qihao */ public void deploySessionBean (String jndi, Class home, Class remote, Class bean) throws Exception SessionBeanDescriptor descriptor = new SessionBeanDescriptor(jndi, home, remote, bean); mockContainer.deploy(descriptor); 5.3.2 算法注釋對于業(yè)務(wù)算法比較復(fù)雜的語句,要寫

23、上相應(yīng)的注釋語。5.3.3可精簡的注釋內(nèi)容注釋中的每一個單詞都要有其不可缺少的意義，注釋里不寫param 這樣的廢話。5.3.4推薦的注釋內(nèi)容 對于API函數(shù)如果存在契約，必須寫明它的前置條件(precondition)，后置條件(postcondition)，及不變式(invariant)。 對于調(diào)用復(fù)雜的API盡量提供代碼示例。 對于已知的Bug需要聲明。 在本函數(shù)中拋出的unchecked exception盡量用throws說明。5.3.5 Null的規(guī)約如果方法允許Null作為參數(shù)，或者允許返回值為Null，必須在JavaDoc中說明。果沒有說明，方法的調(diào)用者不允許使用Null作為參

24、數(shù)，并認(rèn)為返回值是Null Safe的。/* 獲取對象. * return the object to found or null if not found.*/Object get(Integer id) .5.3.6 特殊代碼注釋 代碼質(zhì)量不好但能正常運行，或者還沒有實現(xiàn)的代碼用/TODO: 或 /XXX:聲明 存在錯誤隱患的代碼用/FIXME:聲明6. 聲明6.1 每行聲明變量的數(shù)量推薦一行一個聲明，因為這樣以利于寫注釋。亦即，int level; / indentation levelint size; / size of table要優(yōu)于，int level, size; 不要將不同

25、類型變量的聲明放在同一行，例如：int foo, fooarray; /WRONG!注意：上面的例子中，在類型和標(biāo)識符之間放了一個空格，另一種被允許的替代方式是使用制表符： intlevel; / indentation level intsize; / size of table ObjectcurrentEntry; / currently selected table entry6.2 初始化盡量在聲明局部變量的同時初始化。唯一不這么做的理由是變量的初始值依賴于某些先前發(fā)生的計算。6.3 布局只在代碼塊的開始處聲明變量。（一個塊是指任何被包含在大括號“”和“”中間的代碼。）不要在首次用到

26、該變量時才聲明之。這會把注意力不集中的程序員搞糊涂，同時會妨礙代碼在該作用域內(nèi)的可移植性。 void myMethod() int int1 = 0; / beginning of method blockif (condition) int int2 = 0; / beginning of if block . 該規(guī)則的一個例外是for循環(huán)的索引變量 for (int i = 0; i = 0) ? x : -x;11. 信息輸出所有的提交到服務(wù)器上的編碼（單元測試代碼除外）不允許出現(xiàn)不可關(guān)閉的信息輸出，如：System.out.println（”）; /錯誤12. 代碼范例12.1 Jav

27、a源文件范例下面的例子，展示了如何合理布局一個包含單一公共類的Java源程序。接口的布局與其相似。package java.blah;import java.blah.blahdy.BlahBlah;/* * Class description goes here.類描述 * * version 2009-07-24 創(chuàng)建時間 * author Firstname Lastname 創(chuàng)建人類注釋，包括類描述、創(chuàng)建時間創(chuàng)建人等 */public class Blah extends SomeClass /* A class implementation comment can go here.（該注釋應(yīng)包含任何有關(guān)整個 * 類或接口的信息，而這些信息又不適合作為類/接口文檔注釋。） */ /* classVar1 documentation comment */塊注釋或者單行注釋描述成員 public static int classVar1; 聲明順序: 1. 靜態(tài)成員變量 / Static Fields2. 靜態(tài)初始化塊 / Static Initializers3. 成員變量 / Fields 首先是類的公共變量，隨后是保護變量，再后是包一級別的變量，最后是私有變量。4. 初始化塊 / Initializers