sun推薦的Java編碼規(guī)范

1、Java編碼規(guī)范Java編碼規(guī)范 .11. 說明 .31.1 為什么要有編碼規(guī)范.31.2 版權(quán)聲明 .32. 文件名(File Names) .32.1 文件后綴(File Suffixes).33.1 Java源文件(Java Source Files) .33.1.1 開頭注釋(Beginning Comments) .33.1.2 包和引入(Package and Import Statements) .33.1.3 類和接口聲明(Class and Interface Declarations).34.1 行長度 .34.2 換行(Wrapping Lines) .3/ CONVEN

2、TION INDENTATION .4Object andStillAnother) .4| !(condition5 && condition6) .45. 注釋(Comments) .45.1 實現(xiàn)注釋的格式(Implementation Comment Formats) .45.1.1 塊注釋 .45.1.2 單行注釋(Single-Line Comments) .55.1.3 尾端注釋(Trailing Comments) .55.1.4 行末注釋(End-Of-Line Comments) .55.2 文檔注釋(Documentation Comments) .56.

3、 聲明(Declaration) .56.1 每行聲明變量的數(shù)量(Number Per Line) .56.2 初始化(Initialization) .66.3 布局(Placement) .67.1 簡單語句(Single Statement) .67.2 復(fù)合語句(Compound Statements) .67.3 返回語句(return Statements)s .67.4 if, if-else, if else-if else語句(if, if-else, if else-if else Statements).6 else .6 else if (condition) .6 e

4、lse if (condition) .77.5 for語句(for Statements) .77.6 while語句(while Statements) .77.7 do-while語句(do-while Statements).77.8 switch語句(switch Statements) .77.9 try-catch語句(try-catch Statements).7 catch (ExceptionClass e) .7 catch (ExceptionClass e) .7 finally .78. 空白(White Space).78.1 空行(Blank Lines).78

5、.2 空格(Blank Spaces).79. 命名規(guī)范(Naming Convention) .810. 編程慣例(Programming Practices) .810.1 提供對實例以及類變量的訪問控制(Providing Access to Instance and Class Variables).810.2 引用類變量和類方法(Referring to Class Variables and Methods) .810.4 變量賦值(Variable Assignments) .810.5 其它慣例(Miscellaneous Practices) .910.5.1 圓括號(Par

6、entheses) .910.5.2 返回值(Returning Values).910.5.3 條件運算符“?”前的表達式(Expressions before “?” in the Conditional Operator) .910.5.4 特殊注釋(Special Comments) .911. 代碼范例(Code Examples).911.1 Java源文件范例(Java Source File Example) .91. 說明1.1 為什么要有編碼規(guī)范編碼規(guī)范對于程序員而言尤為重要，有以下幾個原因： 一個軟件的生命周期中，80%的花費在于維護。 幾乎沒有任何一個軟件，在其整個生命

7、同期中，均由最初的開發(fā)人員來維護。 編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新代碼。 如果你將源碼作為產(chǎn)品發(fā)布，就需要確認它是否被很好的打包并且清晰無誤，一如你已構(gòu)建的其它任何產(chǎn)品。為了執(zhí)行規(guī)范，每個軟件開發(fā)人員必須一致遵守編碼規(guī)范。每個人!1.2 版權(quán)聲明本文檔反映的是Sun Microsystem公司，Java語言規(guī)范中的編碼標準部分。主要貢獻者包括：Peter King，Patrick Naughton，Mike DeMoney，Jonni Kanerva，Kathy Walrath以及Scott Hommel。本文檔現(xiàn)由Scott Hommel維護，有關(guān)評論請發(fā)至sh

8、ommel。2. 文件名(File Names)這部分列出了常用的文件名及其后綴。 2.1 文件后綴(File Suffixes) Java程序使用下列文件后綴：2.2 常用文件名(Common File Names)常用的文件名包括：3. 文件組織(File Orgnization)一個文件由被空行分割而成的段落以及標識每個段落的可選注釋共同組成。超過2000行的程序難以閱讀，應(yīng)該盡量避免?！癑ava源文件范例”提供了一個頁面布局合理的Java程序范例。3.1 Java源文件(Java Source Files)每個Java源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關(guān)聯(lián)

9、?？梢詫⑺鼈兒凸差惙湃胪瑐€源文件。公共類必須是這個文件中的第一個類和接口。 Java源文件還遵循以下規(guī)則： 開頭注釋(參見“開頭注釋”) 包和引入語句(參見“包和引入語句) 類和接口聲明(參見“類和接口聲明) 3.1.1 開頭注釋(Beginning Comments)所有的源文件都應(yīng)該在開頭有一個C語言風(fēng)格的注釋，其中列出數(shù)出類名、版本信息，日期和版權(quán)聲明：/ * Classname * Version information * * Date * Copyright notice* /3.1.2 包和引入(Package and Import Statements)在多數(shù)Java源文件中

10、，第一個非注釋行是包語句行。在它之后可以跟引入語句。例如：package java.awt;import java.awt.peer.CanvasPeer;3.1.3 類和接口聲明(Class and Interface Declarations)下表描述了類和接口聲明的免修部分以及它們出現(xiàn)的先后次序。參見“Java源文件范例”中一個包含注釋的例子。4. 縮進排版(Indentation)4個空格常被作為縮進排版的一個單位?？s進的確切解釋并未詳細指定(空格vs.制表符)。一個制表符等于8個空格(而非4個)。4.1 行長度盡量避免一行長度超過80個字符，因為很多終端和工具不能很好處理之。注意：用

11、于文檔是的例子應(yīng)該使用更短的行長，長度一般不超過70個字符。4.2 換行(Wrapping Lines)當(dāng)一個表達式無法容納在一行內(nèi)時，可以依據(jù)如下一般規(guī)則斷開之： 在一個逗號后面斷開。 在一個操作符前面斷開。 寧可選擇較高級別的(higher-level)的斷開，而非較低級別(lower-level)的斷開。 新的一行應(yīng)該與上一行同一級別表達式的開頭處對齊。 如果以上規(guī)則導(dǎo)致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進8個空格。以下是斷開方法的一些例子：someMethod(longExpression1, longExpression2, longExpression3,long

12、Expression4, longExpression5);var = someMethod1(Expression1,someMethod2(longExpression2, longExpression3);以下是兩個斷開算術(shù)表達式的例子。前者更好，因為斷開處位于括號表達式的外邊，這是個較高級別的斷開。longName1 = longName2 * (longName3 + longName4- longNeme5)+ 4 * longName6); /PREFFERlongName1 = longName2 * (longName3 + longName4- longName5) + 4

13、 * longName6; /AVOID以下是兩個縮進方法聲明的例子。前者是常規(guī)情形，后者若使用常規(guī)的縮進方式將會使第二行和第三行移得很靠右，所以代這以縮進8個空格。/ CONVENTION INDENTATION someMethod(int anArg, Object anotherArg,String yetAnotherArg, Object andStillAnother) / INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronized horkingLongMethodName(int anArg,

14、Object anotherArg, String yetAnotherArg, Object andStillAnother) if語句的換行通常使用8個空格的規(guī)則，因為常規(guī)縮進(4個空格)會使語句看起來比較費勁。比如： /DONT USE THIS INDENTATION if (condition1 && condition2)| (condition3 && condition4)| !(condition5 && condition6) /BAD WRAPSdoSomethingAboutIt(); / MAKE THIS LING E

15、ASY TO MISS / USE THIS INDENTATION INSTEAD if (condition1 && condition2)| (condition3 && condition4) | !(condition5 && condition6) doSomethingAboutIt(); / OR USE THISif (condition1 && condition2) | (condition3 && condition4) | !(condition5 && condition

16、6) doSomthingAoutIt(); 這里有三種可行的方法用于處理三元運算表達式： alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta : gamma;5. 注釋(Comments)Java程序有兩類注釋：實現(xiàn)注釋(implementation comments)和文檔注釋(document comments)。實現(xiàn)注釋是那些在C+中見過的，使用/*/和/界定的注釋。

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

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

19、法的內(nèi)部。在功能和方法內(nèi)部的塊注釋應(yīng)該和它們所描述的代碼具有一樣的縮進格式。塊注釋之首應(yīng)該有一個空行，用于把塊注釋和代碼分割開來，比如： / * 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)，就不必在代碼中使用

20、/ *-， 或為他人可能對你的代碼運行indent(1)讓步。參見“文檔注釋”。5.1.2 單行注釋(Single-Line Comments)短注釋可以顯示一行內(nèi)，并與其后的代碼具有一樣的縮進層級。如果一個注釋不能在一行內(nèi)寫完，就該塊注釋(參見“塊注釋”)。單行注釋之前應(yīng)該有一個空行。以下是一個Java代碼中單行注釋的例子：if (condition) / * Handle the condition. */ 5.1.3 尾端注釋(Trailing Comments)極短的注釋可以與它們所要描述的代碼位于同一行，但是應(yīng)該有足夠的空白來分開代碼和注釋。若有多個短注釋出現(xiàn)于大段代碼中，它們應(yīng)該具

21、有相同的縮進。以下是一個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ù)多行的注釋文本；然而，它可以用來注釋掉多行的代碼段。以下是所有三種風(fēng)格的例子： if(foo > 1) / Do a double-filp. else return false; / if (bar > 1)

22、 / / Do a triple-filp. / / / else / return false; / 5.2 文檔注釋(Documentation Comments)注意：此處描述的注釋格式之范例，參見“Java源文件范例”若想了解更多，參見“How to Write Doc Comments for Javadoc”，其中包含了有關(guān)文檔注釋標記的信息(return，param，see)： 若想了解有關(guān)文檔注釋和javadoc的詳細資料，參見javadoc的主頁：文檔注釋描述Java的類、接口、構(gòu)造器、方法，以及字段(field)。每個文檔注釋都會被置于注釋界定符/ */之中，一個注釋對應(yīng)一

23、個類、接口或成員。該注釋應(yīng)位于聲明之前： / * 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.1)或緊跟在聲明后面的單行注釋(見5.1.2)。例如，有關(guān)一個類實現(xiàn)的細節(jié)應(yīng)放入緊跟

24、在類聲明后面的實現(xiàn)塊注釋中，而不是放在文檔注釋中。文檔注釋不能放在一個方法或構(gòu)造器的定義塊中，因為Java會將位于文檔注釋之后的第一個聲明與其相關(guān)聯(lián)。6. 聲明(Declaration)6.1 每行聲明變量的數(shù)量(Number Per Line)推薦一行一個聲明，因為這樣以利于寫注釋。亦即，int level; / indentation levelint size; / size of table要優(yōu)于，int level, size;不要將不同類型變量的聲明放在同一行，例如： int foo, fooarry; / WRONG!注意：上面的例子中，在類型和標識之間放了一個空格，另一種被允許

25、的替代方法是使用制表符：int level; / indentation level int size; / size of tableObject currentEntry; / currently selected table entry6.2 初始化(Initialization)盡量在聲明局部變量的同時進行初始化。唯一 不這么做理由是變量的初始值依賴于某些先前發(fā)生的計算。6.3 布局(Placement)只在代碼塊的開始處聲明變量(一個塊是指任何被包含在大括號“”和“”中間的代碼)。不要在首次用于該變量時才聲明之，這會把注意力不集中的程序員搞糊涂，同時會妨礙代碼在該作用域內(nèi)的可移植性。

26、void myMethod() int int1 = 0; if (condition) int int2 = 0; 該規(guī)則的一個例外是for循環(huán)的索引變量 for (int i = 0; I < maxLoops; i+) 避免聲明的局部變量覆蓋上一級聲明的變量。例如，不要在內(nèi)部代碼塊中聲明相同的變量名： int count; myMethod() if (condition) int count = 0; / AVOID 6.4 類和接口的聲明(Class and Interface Declarations) 當(dāng)編寫類和接口時，應(yīng)該遵守以下格式規(guī)則：1 在方法名與其參數(shù)列表之前的左

27、括號“(”間不要有空格。 左大括號“”位于聲明語句同行的末尾。 右大括號“”另起一行，與相應(yīng)的聲明語句對齊，除非是一個空語句，“”應(yīng)緊跟在“”之后。 class Sample extends Object int ivar1; int ivar2;Sample(int i, int j) ivar1 = i; ivar2 = j; int emptyMethod() 方法與方法之間 以空行分隔。7. 語句(Statements)7.1 簡單語句(Single Statement) 每行至多包含一條語句，例如： argv+; / Correct argc-; / Correctargv+; ar

28、gc-; / AVOID! 7.2 復(fù)合語句(Compound Statements)復(fù)合語句是包含在大括號中的語句序列，形如“ 語句 ”。例如下面各段。 被括其中的語句應(yīng)該較之復(fù)合語句縮進一個層次。 左大括號“”應(yīng)位于復(fù)合語句起始行的行尾；右大括號“”應(yīng)另起一行并與復(fù)合語句首行對齊。 大括號可以被用于所有語句，包括單個語句，只要這些語句是諸如if else或for控制結(jié)構(gòu)的一部分。這樣便于添加語句而無需擔(dān)心由于忘了加括號而引入bug.7.3 返回語句(return Statements)s一個帶返回值的return語句不使用小括號“()”，除非它們以某種方式使返回值更顯見。例如： retur

29、n;return myDisk.size();return (size ? size ; defaultSize);7.4 if, if-else, if else-if else語句(if, if-else, if else-if else Statements)if-else語句應(yīng)該具有如下格式：if (condition) statements; if (condition) statements; else statements; if (condition) statements; else if (condition) statements; else if (condition)

30、 statements; 注意：if語句問題用“”和“”括起來，避免使用如下容易引起錯誤的格式：if (condition) / AVOI! THIS OMITS THE BRACES ! statement;7.5 for語句(for Statements) 一個for語句應(yīng)該具有如下格式： for (initialization; condition; update) statements; 一個空的語句(所有工作都在初始化，條件判斷，更新子句中完成)應(yīng)該具有如下格式：for (initialization; condition; update);當(dāng)在for語句的初始化或更新子句中使用逗號

31、時，避免因使用三個以上變量，而導(dǎo)致復(fù)雜度提高。若需要，可以在for循環(huán)之前(為初始化子句)或for循環(huán)末尾(為更新子句)使用單獨的語句。7.6 while語句(while Statements) 一個while語句應(yīng)該具有如下格式： while (condition) statements; 一個空的while語句應(yīng)該具有如下格式： while (condition);7.7 do-while語句(do-while Statements) 一個do-while語句應(yīng)該具有如下格式： do statements; while (condition);7.8 switch語句(switch Sta

32、tements) 一個switch語句應(yīng)該具有如下格式： switch (condition) case ABC:statements; / * falls through */ case DEF:statements; break; case XYZ:statements; break; 每當(dāng)一個case順著往下執(zhí)行時(因為沒有break語句)，通常應(yīng)在break語句的位置添加注釋。上面的示例代碼中就包含注釋/ *falls through */。7.9 try-catch語句(try-catch Statements) 一個try-catch語句應(yīng)該具有如下格式： try statemen

33、ts; catch (ExceptionClass e) statements; 一個try-catch語句后面也可能跟著一個finally語句，不論try代碼塊是否順利執(zhí)行完，它都會被執(zhí)行。 try statements; catch (ExceptionClass e) statements; finally statements; 8. 空白(White Space) 8.1 空行(Blank Lines)空行將邏輯相關(guān)的代碼段分隔開，以提高可讀性。 下列情況應(yīng)總是使用兩個空行： 一個源文件的兩個片段(section)之間。 類聲明和接口聲明之間。 下列情況應(yīng)該總是使用一個空行： 兩個方

34、法之間。 方法內(nèi)的局部變量和方法的第一條語句之間。 塊注釋(參見“5.1.1”)或單行注釋(參見5.1.2)之前。 一個方法內(nèi)的兩個邏輯段之間，用以提高可讀性。 8.2 空格(Blank Spaces) 下列情況應(yīng)該使用空格： 一個緊跟著括號的關(guān)鍵應(yīng)該被空格分開，例如： while (true) . 注意：空格不應(yīng)該置于方法名與其左括號之間，這將有助于區(qū)分關(guān)鍵字和方法調(diào)用。 空白應(yīng)該位于參數(shù)列表中逗號的后面。 所有的二元運算符，除了“.”，應(yīng)該使用空格將之與操作數(shù)分開。一元操作符和操作數(shù)之間不應(yīng)該加空格，比如：負號(“-”)，自增(“+”)和自減(“-”)。例如：a += c + d; a =

35、 (a + b) / (c * d);while (d+ + s+) n+; printSize(“size is ” + foo + “n”); for語句中的表達式應(yīng)該被空格分開，例如： for (expr1; expr2; expr3) 強制轉(zhuǎn)型后應(yīng)該跟一個空格，例如：myMethod(byte) aNum, (Object) x); myMethod(int) (cp + 5), (int) (i + 3) + 1); 9. 命名規(guī)范(Naming Convention) 9.1包(Packages)一個唯一包名的前綴總是全部小寫的ASC字母并且是一個頂級域名，通常是com，gov，edu，mil，net，org，或1981年ISO 3166標準所指定的標識的國家的英文雙字符代碼。包名的后續(xù)部分根據(jù)不同機構(gòu)各自內(nèi)部的命名規(guī)范而不盡相同。這類命名規(guī)范可能以特定目錄名的組成來區(qū)分部門(department)，項目(project)，機器(machine)，或注冊名(login names)。例如： com.sun.engcom.apple.quicktime.v2 edu.cmu.cs.bovik.cheese 9.2類(Classes)類名是一個名詞，采用大小寫混合方式，每個單詞的首字母大寫。盡量使你的類名簡潔而富于描述。使用