JavaCode--我愛(ài)你,芳兒

編碼規(guī)范對(duì)于程序員而言尤為重要，有以下幾個(gè)原因：

- 一個(gè)軟件的生命周期中，80%的花費(fèi)在于維護(hù)
- 幾乎沒(méi)有任何一個(gè)軟件，在其整個(gè)生命周期中，均由最初的開(kāi)發(fā)人員來(lái)維護(hù)
- 編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼
- 如果你將源碼作為產(chǎn)品發(fā)布，就需要確任它是否被很好的打包并且清晰無(wú)誤，一如你已構(gòu)建的其它任何產(chǎn)品

為了執(zhí)行規(guī)范，每個(gè)軟件開(kāi)發(fā)人員必須一致遵守編碼規(guī)范。每個(gè)人。

本文檔反映的是Sun MicroSystems公司，Java語(yǔ)言規(guī)范中的編碼標(biāo)準(zhǔn)部分。主要貢獻(xiàn)者包括：Peter King，Patrick Naughton，Mike DeMoney，Jonni Kanerva，Kathy Walrath以及Scott Hommel。

本文檔現(xiàn)由Scott Hommel維護(hù)，有關(guān)評(píng)論意見(jiàn)請(qǐng)發(fā)至shommel@eng.sun.com

這部分列出了常用的文件名及其后綴。

Java程序使用下列文件后綴：

文件類(lèi)別	文件后綴
Java源文件	.java
Java字節(jié)碼文件	.class

常用的文件名包括：

文件名	用途
GNUmakefile	makefiles的首選文件名。我們采用gnumake來(lái)創(chuàng)建（build）軟件。
README	概述特定目錄下所含內(nèi)容的文件的首選文件名

一個(gè)文件由被空行分割而成的段落以及標(biāo)識(shí)每個(gè)段落的可選注釋共同組成。超過(guò)2000行的程序難以閱讀，應(yīng)該盡量避免。"Java源文件范例"提供了一個(gè)布局合理的Java程序范例。

所有的源文件都應(yīng)該在開(kāi)頭有一個(gè)C語(yǔ)言風(fēng)格的注釋?zhuān)渲辛谐鲱?lèi)名、版本信息、日期和版權(quán)聲明：

  /*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/

在多數(shù)Java源文件中，第一個(gè)非注釋行是包語(yǔ)句。在它之后可以跟引入語(yǔ)句。例如：

  package java.awt;
import java.awt.peer.CanvasPeer;

4個(gè)空格常被作為縮進(jìn)排版的一個(gè)單位。縮進(jìn)的確切解釋并未詳細(xì)指定(空格 vs. 制表符)。一個(gè)制表符等于8個(gè)空格(而非4個(gè))。

盡量避免一行的長(zhǎng)度超過(guò)80個(gè)字符，因?yàn)楹芏嘟K端和工具不能很好處理之。

注意：用于文檔中的例子應(yīng)該使用更短的行長(zhǎng)，長(zhǎng)度一般不超過(guò)70個(gè)字符。

當(dāng)一個(gè)表達(dá)式無(wú)法容納在一行內(nèi)時(shí)，可以依據(jù)如下一般規(guī)則斷開(kāi)之：

- 在一個(gè)逗號(hào)后面斷開(kāi)
- 在一個(gè)操作符前面斷開(kāi)
- 寧可選擇較高級(jí)別(higher-level)的斷開(kāi)，而非較低級(jí)別(lower-level)的斷開(kāi)
- 新的一行應(yīng)該與上一行同一級(jí)別表達(dá)式的開(kāi)頭處對(duì)齊
- 如果以上規(guī)則導(dǎo)致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進(jìn)8個(gè)空格。

以下是斷開(kāi)方法調(diào)用的一些例子：

  someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
var = someMethod1(longExpression1,
someMethod2(longExpression2,
longExpression3));

以下是兩個(gè)斷開(kāi)算術(shù)表達(dá)式的例子。前者更好，因?yàn)閿嚅_(kāi)處位于括號(hào)表達(dá)式的外邊，這是個(gè)較高級(jí)別的斷開(kāi)。

  longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6; //PREFFER
longName1 = longName2 * (longName3 + longName4
- longName5) + 4 * longname6; //AVOID

以下是兩個(gè)縮進(jìn)方法聲明的例子。前者是常規(guī)情形。后者若使用常規(guī)的縮進(jìn)方式將會(huì)使第二行和第三行移得很靠右，所以代之以縮進(jìn)8個(gè)空格

  //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 andStillAnother) {
...
}

if語(yǔ)句的換行通常使用8個(gè)空格的規(guī)則，因?yàn)槌Ｒ?guī)縮進(jìn)(4個(gè)空格)會(huì)使語(yǔ)句體看起來(lái)比較費(fèi)勁。比如：

  //DON’T 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 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
//OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}

這里有三種可行的方法用于處理三元運(yùn)算表達(dá)式：

  alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression)
? beta
: gamma;

Java程序有兩類(lèi)注釋?zhuān)簩?shí)現(xiàn)注釋(implementation comments)和文檔注釋(document comments)。實(shí)現(xiàn)注釋是那些在C++中見(jiàn)過(guò)的，使用/*...*/和//界定的注釋。文檔注釋(被稱(chēng)為"doc comments")是Java獨(dú)有的，并由/**...*/界定。文檔注釋可以通過(guò)javadoc工具轉(zhuǎn)換成HTML文件。

實(shí)現(xiàn)注釋用以注釋代碼或者實(shí)現(xiàn)細(xì)節(jié)。文檔注釋從實(shí)現(xiàn)自由(implementation-free)的角度描述代碼的規(guī)范。它可以被那些手頭沒(méi)有源碼的開(kāi)發(fā)人員讀懂。

注釋?xiě)?yīng)被用來(lái)給出代碼的總括，并提供代碼自身沒(méi)有提供的附加信息。注釋?xiě)?yīng)該僅包含與閱讀和理解程序有關(guān)的信息。例如，相應(yīng)的包如何被建立或位于哪個(gè)目錄下之類(lèi)的信息不應(yīng)包括在注釋中。

在注釋里，對(duì)設(shè)計(jì)決策中重要的或者不是顯而易見(jiàn)的地方進(jìn)行說(shuō)明是可以的，但應(yīng)避免提供代碼中己清晰表達(dá)出來(lái)的重復(fù)信息。多余的的注釋很容易過(guò)時(shí)。通常應(yīng)避免那些代碼更新就可能過(guò)時(shí)的注釋。

注意：頻繁的注釋有時(shí)反映出代碼的低質(zhì)量。當(dāng)你覺(jué)得被迫要加注釋的時(shí)候，考慮一下重寫(xiě)代碼使其更清晰。

注釋不應(yīng)寫(xiě)在用星號(hào)或其他字符畫(huà)出來(lái)的大框里。注釋不應(yīng)包括諸如制表符和回退符之類(lèi)的特殊字符。

程序可以有4種實(shí)現(xiàn)注釋的風(fēng)格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。

塊注釋通常用于提供對(duì)文件，方法，數(shù)據(jù)結(jié)構(gòu)和算法的描述。塊注釋被置于每個(gè)文件的開(kāi)始處以及每個(gè)方法之前。它們也可以被用于其他地方，比如方法內(nèi)部。在功能和方法內(nèi)部的塊注釋?xiě)?yīng)該和它們所描述的代碼具有一樣的縮進(jìn)格式。

塊注釋之首應(yīng)該有一個(gè)空行，用于把塊注釋和代碼分割開(kāi)來(lái)，比如：

  /*
* Here is a block comment.
*/

塊注釋可以以/*-開(kāi)頭，這樣indent(1)就可以將之識(shí)別為一個(gè)代碼塊的開(kāi)始，而不會(huì)重排它。

  /*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
*    one
*        two
*            three
*/

注意：如果你不使用indent(1)，就不必在代碼中使用/*-，或?yàn)樗丝赡軐?duì)你的代碼運(yùn)行indent(1)作讓步。

極短的注釋可以與它們所要描述的代碼位于同一行，但是應(yīng)該有足夠的空白來(lái)分開(kāi)代碼和注釋。若有多個(gè)短注釋出現(xiàn)于大段代碼中，它們應(yīng)該具有相同的縮進(jìn)。

以下是一個(gè)Java代碼中尾端注釋的例子：

  if (a == 2) {
return TRUE;              /* special case */
} else {
return isPrime(a);         /* works only for odd a */
}

注釋界定符"http://"，可以注釋掉整行或者一行中的一部分。它一般不用于連續(xù)多行的注釋文本；然而，它可以用來(lái)注釋掉連續(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;
//}

推薦一行一個(gè)聲明，因?yàn)檫@樣以利于寫(xiě)注釋。亦即，

  int level;  // indentation level
int size;   // size of table

要優(yōu)于，

int level, size;

不要將不同類(lèi)型變量的聲明放在同一行，例如：

  int foo,  fooarray[];   //WRONG!

注意：上面的例子中，在類(lèi)型和標(biāo)識(shí)符之間放了一個(gè)空格，另一種被允許的替代方式是使用制表符：

  int		level;         // indentation level
int		size;          // size of table
Object	currentEntry;  // currently selected table entry

盡量在聲明局部變量的同時(shí)初始化。唯一不這么做的理由是變量的初始值依賴(lài)于某些先前發(fā)生的計(jì)算。

只在代碼塊的開(kāi)始處聲明變量。（一個(gè)塊是指任何被包含在大括號(hào)"{"和"}"中間的代碼。）不要在首次用到該變量時(shí)才聲明之。這會(huì)把注意力不集中的程序員搞糊涂，同時(shí)會(huì)妨礙代碼在該作用域內(nèi)的可移植性。

  void myMethod() {
int int1 = 0;         // beginning of method block
if (condition) {
int int2 = 0;     // beginning of "if" block
...
}
}

該規(guī)則的一個(gè)例外是for循環(huán)的索引變量

  for (int i = 0; i < maxLoops; i++) { ... }

避免聲明的局部變量覆蓋上一級(jí)聲明的變量。例如，不要在內(nèi)部代碼塊中聲明相同的變量名：

  int count;
...
myMethod() {
if (condition) {
int count = 0;     // AVOID!
...
}
...
}

當(dāng)編寫(xiě)類(lèi)和接口是，應(yīng)該遵守以下格式規(guī)則：

- 在方法名與其參數(shù)列表之前的左括號(hào)"("間不要有空格
- 左大括號(hào)"{"位于聲明語(yǔ)句同行的末尾
- 右大括號(hào)"}"另起一行，與相應(yīng)的聲明語(yǔ)句對(duì)齊，除非是一個(gè)空語(yǔ)句，"}"應(yīng)緊跟在"{"之后

  class Sample extends Object {
int ivar1;
int ivar2;
Sample(int i, int j) {
ivar1 = i;
ivar2 = j;
}
int emptyMethod() {}
...
}

每行至多包含一條語(yǔ)句，例如：

  argv++;       // Correct
argc--;       // Correct
argv++; argc--;       // AVOID!

復(fù)合語(yǔ)句是包含在大括號(hào)中的語(yǔ)句序列，形如"{ 語(yǔ)句 }"。例如下面各段。

- 被括其中的語(yǔ)句應(yīng)該較之復(fù)合語(yǔ)句縮進(jìn)一個(gè)層次
- 左大括號(hào)"{"應(yīng)位于復(fù)合語(yǔ)句起始行的行尾；右大括號(hào)"}"應(yīng)另起一行并與復(fù)合語(yǔ)句首行對(duì)齊。
- 大括號(hào)可以被用于所有語(yǔ)句，包括單個(gè)語(yǔ)句，只要這些語(yǔ)句是諸如if-else或for控制結(jié)構(gòu)的一部分。這樣便于添加語(yǔ)句而無(wú)需擔(dān)心由于忘了加括號(hào)而引入bug。

一個(gè)帶返回值的return語(yǔ)句不使用小括號(hào)"()"，除非它們以某種方式使返回值更為顯見(jiàn)。例如：

  return;
return myDisk.size();
return (size ? size : defaultSize);

if-else語(yǔ)句應(yīng)該具有如下格式：

  if (condition) {
statements;
}
if (condition) {
statements;
} else {
statements;
}
if (condition) {
statements;
} else if (condition) {
statements;
} else{
statements;
}

注意：if語(yǔ)句總是用"{"和"}"括起來(lái)，避免使用如下容易引起錯(cuò)誤的格式：

  if (condition) //AVOID! THIS OMITS THE BRACES {}!
statement;

一個(gè)for語(yǔ)句應(yīng)該具有如下格式：

  for (initialization; condition; update) {
statements;
}

一個(gè)空的for語(yǔ)句(所有工作都在初始化，條件判斷，更新子句中完成）應(yīng)該具有如下格式：

  for (initialization; condition; update);

當(dāng)在for語(yǔ)句的初始化或更新子句中使用逗號(hào)時(shí)，避免因使用三個(gè)以上變量，而導(dǎo)致復(fù)雜度提高。若需要，可以在for循環(huán)之前(為初始化子句)或for循環(huán)末尾(為更新子句)使用單獨(dú)的語(yǔ)句。

一個(gè)while語(yǔ)句應(yīng)該具有如下格式

  while (condition) {
statements;
}

一個(gè)空的while語(yǔ)句應(yīng)該具有如下格式：

  while (condition);

一個(gè)do-while語(yǔ)句應(yīng)該具有如下格式：

  do {
statements;
} while (condition);

一個(gè)switch語(yǔ)句應(yīng)該具有如下格式：

  switch (condition) {
case ABC:
statements;
/* falls through */
case DEF:
statements;
break;
case XYZ:
statements;
break;
default:
statements;
break;
}

每當(dāng)一個(gè)case順著往下執(zhí)行時(shí)(因?yàn)闆](méi)有break語(yǔ)句)，通常應(yīng)在break語(yǔ)句的位置添加注釋。上面的示例代碼中就包含注釋/* falls through */。

一個(gè)try-catch語(yǔ)句應(yīng)該具有如下格式：

  try {
statements;
} catch (ExceptionClass e) {
statements;
}

一個(gè)try-catch語(yǔ)句后面也可能跟著一個(gè)finally語(yǔ)句，不論try代碼塊是否順利執(zhí)行完，它都會(huì)被執(zhí)行。

  try {
statements;
} catch (ExceptionClass e) {
statements;
} finally {
statements;
}

空行將邏輯相關(guān)的代碼段分隔開(kāi)，以提高可讀性。

下列情況應(yīng)該總是使用兩個(gè)空行：

- 一個(gè)源文件的兩個(gè)片段(section)之間
- 類(lèi)聲明和接口聲明之間

下列情況應(yīng)該總是使用一個(gè)空行：

下列情況應(yīng)該使用空格：

- 一個(gè)緊跟著括號(hào)的關(guān)鍵字應(yīng)該被空格分開(kāi)，例如：

  while (true) {
...
}

    a += c + d;
a = (a + b) / (c * d);
while (d++ = s++) {
n++;
}
printSize("size is " + foo + "\n");

    for (expr1; expr2; expr3)

    myMethod((byte) aNum, (Object) x);
myMethod((int) (cp + 5), ((int) (i + 3)) + 1);

命名規(guī)范使程序更易讀，從而更易于理解。它們也可以提供一些有關(guān)標(biāo)識(shí)符功能的信息，以助于理解代碼，例如，不論它是一個(gè)常量，包，還是類(lèi)。

標(biāo)識(shí)符類(lèi)型	命名規(guī)則	例子
包(Packages)	一個(gè)唯一包名的前綴總是全部小寫(xiě)的ASCII字母并且是一個(gè)頂級(jí)域名，通常是com，edu，gov，mil，net，org，或1981年ISO 3166標(biāo)準(zhǔn)所指定的標(biāo)識(shí)國(guó)家的英文雙字符代碼。包名的后續(xù)部分根據(jù)不同機(jī)構(gòu)各自?xún)?nèi)部的命名規(guī)范而不盡相同。這類(lèi)命名規(guī)范可能以特定目錄名的組成來(lái)區(qū)分部門(mén)(department)，項(xiàng)目(project)，機(jī)器(machine)，或注冊(cè)名(login names)。	com.sun.eng com.apple.quicktime.v2 edu.cmu.cs.bovik.cheese
類(lèi)(Classes)	命名規(guī)則：類(lèi)名是個(gè)一名詞，采用大小寫(xiě)混合的方式，每個(gè)單詞的首字母大寫(xiě)。盡量使你的類(lèi)名簡(jiǎn)潔而富于描述。使用完整單詞，避免縮寫(xiě)詞(除非該縮寫(xiě)詞被更廣泛使用，像URL，HTML)	class Raster; class ImageSprite;
接口(Interfaces)	命名規(guī)則：大小寫(xiě)規(guī)則與類(lèi)名相似	interface RasterDelegate; interface Storing;
方法(Methods)	方法名是一個(gè)動(dòng)詞，采用大小寫(xiě)混合的方式，第一個(gè)單詞的首字母小寫(xiě)，其后單詞的首字母大寫(xiě)。	run(); runFast(); getBackground();
變量(Variables)	除了變量名外，所有實(shí)例，包括類(lèi)，類(lèi)常量，均采用大小寫(xiě)混合的方式，第一個(gè)單詞的首字母小寫(xiě)，其后單詞的首字母大寫(xiě)。變量名不應(yīng)以下劃線(xiàn)或美元符號(hào)開(kāi)頭，盡管這在語(yǔ)法上是允許的。 變量名應(yīng)簡(jiǎn)短且富于描述。變量名的選用應(yīng)該易于記憶，即，能夠指出其用途。盡量避免單個(gè)字符的變量名，除非是一次性的臨時(shí)變量。臨時(shí)變量通常被取名為i，j，k，m和n，它們一般用于整型；c，d，e，它們一般用于字符型。	char c; int i; float myWidth;
實(shí)例變量(Instance Variables)	大小寫(xiě)規(guī)則和變量名相似，除了前面需要一個(gè)下劃線(xiàn)	int _employeeId; String _name; Customer _customer;
常量(Constants)	類(lèi)常量和ANSI常量的聲明，應(yīng)該全部大寫(xiě)，單詞間用下劃線(xiàn)隔開(kāi)。(盡量避免ANSI常量，容易引起錯(cuò)誤)	static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1;

若沒(méi)有足夠理由，不要把實(shí)例或類(lèi)變量聲明為公有。通常，實(shí)例變量無(wú)需顯式的設(shè)置(set)和獲取(gotten)，通常這作為方法調(diào)用的邊緣效應(yīng) (side effect)而產(chǎn)生。

一個(gè)具有公有實(shí)例變量的恰當(dāng)例子，是類(lèi)僅作為數(shù)據(jù)結(jié)構(gòu)，沒(méi)有行為。亦即，若你要使用一個(gè)結(jié)構(gòu)(struct)而非一個(gè)類(lèi)(如果java支持結(jié)構(gòu)的話(huà))，那么把類(lèi)的實(shí)例變量聲明為公有是合適的。

避免用一個(gè)對(duì)象訪(fǎng)問(wèn)一個(gè)類(lèi)的靜態(tài)變量和方法。應(yīng)該用類(lèi)名替代。例如：

  classMethod();             //OK
AClass.classMethod();      //OK
anObject.classMethod();    //AVOID!

位于for循環(huán)中作為計(jì)數(shù)器值的數(shù)字常量，除了-1,0和1之外，不應(yīng)被直接寫(xiě)入代碼。

避免在一個(gè)語(yǔ)句中給多個(gè)變量賦相同的值。它很難讀懂。例如：

  fooBar.fChar = barFoo.lchar = 'c'; // AVOID!

不要將賦值運(yùn)算符用在容易與相等關(guān)系運(yùn)算符混淆的地方。例如：

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

應(yīng)該寫(xiě)成

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

不要使用內(nèi)嵌(embedded)賦值運(yùn)算符試圖提高運(yùn)行時(shí)的效率，這是編譯器的工作。例如：

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

應(yīng)該寫(xiě)成

  a = b + c;
d = a + r;

一般而言，在含有多種運(yùn)算符的表達(dá)式中使用圓括號(hào)來(lái)避免運(yùn)算符優(yōu)先級(jí)問(wèn)題，是個(gè)好方法。即使運(yùn)算符的優(yōu)先級(jí)對(duì)你而言可能很清楚，但對(duì)其他人未必如此。你不能假設(shè)別的程序員和你一樣清楚運(yùn)算符的優(yōu)先級(jí)。

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

設(shè)法讓你的程序結(jié)構(gòu)符合目的。例如：

  if (booleanExpression) {
return true;
} else {
return false;
}

應(yīng)該代之以如下方法：

  return booleanExpression;

類(lèi)似地：

  if (condition) {
return x;
}
return y;

應(yīng)該寫(xiě)做：

  return (condition ? x : y);

如果一個(gè)包含二元運(yùn)算符的表達(dá)式出現(xiàn)在三元運(yùn)算符" ? : "的"?"之前，那么應(yīng)該給表達(dá)式添上一對(duì)圓括號(hào)。例如：

  (x >= 0) ? x : -x;

在注釋中使用XXX來(lái)標(biāo)識(shí)某些未實(shí)現(xiàn)(bogus)的但可以工作(works)的內(nèi)容。用FIXME來(lái)標(biāo)識(shí)某些假的和錯(cuò)誤的內(nèi)容。