Java語言編碼規範（1）(轉)

Java語言編碼規範（1）(轉)[@more@]2 檔名(File Names)
這部分列出了常用的檔名及其字尾。
2.1 檔案字尾(File Suffixes)
Java程式使用下列檔案字尾：
檔案類別 檔案字尾
Java原始檔 .java
Java位元組碼檔案 .class
2.2 常用檔名(Common File Names)
常用的檔名包括：
檔名 用途
GNUmakefile makefiles的首選檔名。我們採用gnumake來建立（build）軟體。
README 概述特定目錄下所含內容的檔案的首選檔名
3 檔案組織(File Organization)
一個檔案由被空行分割而成的段落以及標識每個段落的可選註釋共同組成。超過2000行的程式難以閱讀，應該儘量避免。"Java原始檔範例"提供了一個佈局合理的Java程式範例。
3.1 Java原始檔(Java Source Files)
每個Java原始檔都包含一個單一的公共類或介面。若私有類和介面與一個公共類相關聯，可以將它們和公共類放入同一個原始檔。公共類必須是這個檔案中的第一個類或介面。
Java原始檔還遵循以下規則：
- 開頭註釋（參見"開頭註釋"）
- 包和引入語句（參見"包和引入語句"）
- 類和介面宣告（參見"類和介面宣告"）
3.1.1 開頭註釋(Beginning Comments)
所有的原始檔都應該在開頭有一個C語言風格的註釋，其中列出類名、版本資訊、日期和版權宣告：
/*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/

3.1.2 包和引入語句(Package and Import Statements)
在多數Java原始檔中，第一個非註釋行是包語句。在它之後可以跟引入語句。例如：
package java.awt;

import java.awt.peer.CanvasPeer;

3.1.3 類和介面宣告(Class and Interface Declarations)
下表描述了類和介面宣告的各個部分以及它們出現的先後次序。參見"Java原始檔範例"中一個包含註釋的例子。
類/介面宣告的各部分 註解
1 類/介面文件註釋(/**……*/) 該註釋中所需包含的資訊，參見"文件註釋"
2 類或介面的宣告
3 類/介面實現的註釋(/*……*/)如果有必要的話 該註釋應包含任何有關整個類或介面的資訊，而這些資訊又不適合作為類/介面文件註釋。
4 類的(靜態)變數 首先是類的公共變數，隨後是保護變數，再後是包一級別的變數(沒有訪問修飾符，access modifier)，最後是私有變數。
5 例項變數 首先是公共級別的，隨後是保護級別的，再後是包一級別的(沒有訪問修飾符)，最後是私有級別的。
6 構造器
7 方法 這些方法應該按功能，而非作用域或訪問許可權，分組。例如，一個私有的類方法可以置於兩個公有的例項方法之間。其目的是為了更便於閱讀和理解程式碼。
4 縮排排版(Indentation)
4個空格常被作為縮排排版的一個單位。縮排的確切解釋並未詳細指定(空格 vs. 製表符)。一個製表符等於8個空格(而非4個)。
4.1 行長度(Line Length)
儘量避免一行的長度超過80個字元，因為很多終端和工具不能很好處理之。
注意：用於文件中的例子應該使用更短的行長，長度一般不超過70個字元。
4.2 換行(Wrapping Lines)
當一個表示式無法容納在一行內時，可以依據如下一般規則斷開之：
- 在一個逗號後面斷開
- 在一個運算子前面斷開
- 寧可選擇較高階別(higher-level)的斷開，而非較低階別(lower-level)的斷開
- 新的一行應該與上一行同一級別表示式的開頭處對齊
- 如果以上規則導致你的程式碼混亂或者使你的程式碼都堆擠在右邊，那就代之以縮排8個空格。
以下是斷開方法呼叫的一些例子：
someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);

var = someMethod1(longExpression1,
someMethod2(longExpression2,
longExpression3));

以下是兩個斷開算術表示式的例子。前者更好，因為斷開處位於括號表示式的外邊，這是個較高階別的斷開。
longName1 = longName2 * (longName3 + longName4 - longName5)
+ 4 * longname6; //PREFFER

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

以下是兩個縮排方法宣告的例子。前者是常規情形。後者若使用常規的縮排方式將會使第二行和第三行移得很靠右，所以代之以縮排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 andStillAnother) {
...
}

if語句的換行通常使用8個空格的規則，因為常規縮排(4個空格)會使語句體看起來比較費勁。比如：
//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();
}

這裡有三種可行的方法用於處理三元運算表示式：
alpha = (aLongBooleanExpression) ? beta : gamma;

alpha = (aLongBooleanExpression) ? beta
: gamma;

alpha = (aLongBooleanExpression)
? beta
: gamma;
5 註釋(Comments)

Java程式有兩類註釋：實現註釋(implementation comments)和文件註釋(document comments)。實現註釋是那些在C++中見過的，使用/*...*/和//界定的註釋。文件註釋(被稱為"doc comments")是Java獨有的，並由/**...*/界定。文件註釋可以透過javadoc工具轉換成HTML檔案。

實現註釋用以註釋程式碼或者實現細節。文件註釋從實現自由(implementation-free)的角度描述程式碼的規範。它可以被那些手頭沒有原始碼的開發人員讀懂。

註釋應被用來給出程式碼的總括，並提供程式碼自身沒有提供的附加資訊。註釋應該僅包含與閱讀和理解程式有關的資訊。例如，相應的包如何被建立或位於哪個目錄下之類的資訊不應包括在註釋中。

在註釋裡，對設計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應避擴音供程式碼中己清晰表達出來的重複資訊。多餘的的註釋很容易過時。通常應避免那些程式碼更新就可能過時的註釋。

注意：頻繁的註釋有時反映出程式碼的低質量。當你覺得被迫要加註釋的時候，考慮一下重寫程式碼使其更清晰。

註釋不應寫在用星號或其他字元畫出來的大框裡。註釋不應包括諸如製表符和回退符之類的特殊字元。

5.1 實現註釋的格式(Implementation Comment Formats)

程式可以有4種實現註釋的風格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。

5.1.1 塊註釋(Block Comments)

塊註釋通常用於提供對檔案，方法，資料結構和演算法的描述。塊註釋被置於每個檔案的開始處以及每個方法之前。它們也可以被用於其他地方，比如方法內部。在功能和方法內部的塊註釋應該和它們所描述的程式碼具有一樣的縮排格式。

塊註釋之首應該有一個空行，用於把塊註釋和程式碼分割開來，比如：


/*
* 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)作讓步。

參見"文件註釋"

5.1.2 單行註釋(Single-Line Comments)

短註釋可以顯示在一行內，並與其後的程式碼具有一樣的縮排層級。如果一個註釋不能在一行內寫完，就該採用塊註釋(參見"塊註釋")。單行註釋之前應該有一個空行。以下是一個Java程式碼中單行註釋的例子：


if (condition) {

/* Handle the condition. */
...
}

5.1.3 尾端註釋(Trailing Comments)

極短的註釋可以與它們所要描述的程式碼位於同一行，但是應該有足夠的空白來分開程式碼和註釋。若有多個短註釋出現於大段程式碼中，它們應該具有相同的縮排。

以下是一個Java程式碼中尾端註釋的例子：

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


5.1.4 行末註釋(End-Of-Line Comments)

註釋界定符"//"，可以註釋掉整行或者一行中的一部分。它一般不用於連續多行的註釋文字；然而，它可以用來註釋掉連續多行的程式碼段。以下是所有三種風格的例子：


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 文件註釋(Documentation Comments)

注意：此處描述的註釋格式之範例，參見"Java原始檔範例"

若想了解更多，參見"How to Write Doc Comments for Javadoc"，其中包含了有關文件註釋標記的資訊(@return, @param, @see)：



若想了解更多有關文件註釋和javadoc的詳細資料，參見javadoc的主頁：



文件註釋描述Java的類、介面、構造器，方法，以及欄位(field)。每個文件註釋都會被置於註釋定界符/**...*/之中，一個註釋對應一個類、介面或成員。該註釋應位於宣告之前：


/**
* The Example class provides ...
*/
public class Example { ...


注意頂層(top-level)的類和介面是不縮排的，而其成員是縮排的。描述類和介面的文件註釋的第一行(/**)不需縮排；隨後的文件註釋每行都縮排1格(使星號縱向對齊)。成員，包括建構函式在內，其文件註釋的第一行縮排4格，隨後每行都縮排5格。

若你想給出有關類、介面、變數或方法的資訊，而這些資訊又不適合寫在文件中，則可使用實現塊註釋(見5.1.1)或緊跟在宣告後面的單行註釋(見5.1.2)。例如，有關一個類實現的細節，應放入緊跟在類宣告後面的實現塊註釋中，而不是放在文件註釋中。

文件註釋不能放在一個方法或構造器的定義塊中，因為Java會將位於文件註釋之後的第一個宣告與其相關聯。

6 宣告(Declarations)

6.1 每行宣告變數的數量(Number Per Line)

推薦一行一個宣告，因為這樣以利於寫註釋。亦即，


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


要優於，

int level, size;

不要將不同型別變數的宣告放在同一行，例如：


int foo, fooarray[]; //WRONG!


注意：上面的例子中，在型別和識別符號之間放了一個空格，另一種被允許的替代方式是使用製表符：


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


6.2 初始化(Initialization)

儘量在宣告區域性變數的同時初始化。唯一不這麼做的理由是變數的初始值依賴於某些先前發生的計算。