1. 縮進排版(Indentation)
4個空格常被作為縮進排版的一個單位。縮進的確切解釋並未詳細指定(空格 vs. 制表符)。一個制表符等於n個空格(視具體的編輯器而定，Eclipse默認一個制表符為4個字符)。
3.1 行長度(Line Length)
盡量避免一行的長度超過80個字符，因為很多終端和工具不能很好處理之。
注意：鑒於Eclipse開發工具工作區的左側和右側都被非代碼編輯器所占據，因此建議每行的代碼長度不要超過70個字符。
3.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; //推薦使用 longName1 = longName2 * ( longName3 + longName4 - longName5 ) + 4 * longname6; //應避免這樣使用 |
以下是兩個縮進方法聲明的例子。前者是常規情形。后者若使用常規的縮進方式將會使第二行和第三行移得很靠右，所以代之以縮進空格，盡量與運算符或者括號對齊。
| //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; |
2. 注釋(Comments)
Java程序有兩類注釋：實現注釋(implementation comments)和文檔注釋(document comments)。實現注釋是那些在C++中見過的，使用/*...*/和//界定的注釋。文檔注釋是Java獨有的，並由/**...*/界定。文檔注釋可以通過javadoc工具轉換成HTML文件。
實現注釋用以注釋代碼或者實現細節。文檔注釋從實現自由(implementation-free)的角度描述代碼的規范。它可以被那些手頭沒有源碼的開發人員讀懂。
注釋應被用來給出代碼的總括，並提供代碼自身沒有提供的附加信息。注釋應該僅包含與閱讀和理解程序有關的信息。例如，相應的包如何被建立或位於哪個目錄下之類的信息不應包括在注釋中。
在注釋里，對設計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應避免提供代碼中己清晰表達出來的重復信息。通常應避免那些代碼更新就可能過時的注釋。
注意：頻繁的注釋有時反映出代碼的低質量。當你覺得被迫要加注釋的時候，考慮一下重寫代碼使其更清晰。
注釋不應寫在用星號或其他字符畫出來的大框里。注釋不應包括諸如制表符和回退符之類的特殊字符。
4.1 實現注釋的格式(Implementation Comment Formats)
程序可以有4種實現注釋的風格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。
4.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)作讓步。
4.1.2 單行注釋(Single-Line Comments)
短注釋可以顯示在一行內，並與其后的代碼具有一樣的縮進層級。如果一個注釋不能在一行內寫完，就該采用塊注釋(參見“塊注釋”)。單行注釋之前應該有一個空行。以下是一個Java代碼中單行注釋的例子：
if (condition) {
/* Handle the condition. */
...
}
4.1.3 尾端注釋(Trailing Comments)
極短的注釋可以與它們所要描述的代碼位於同一行，但是應該有足夠的空白來分開代碼和注釋。若有多個短注釋出現於大段代碼中，它們應該具有相同的縮進。
以下是一個Java代碼中尾端注釋的例子：
if (a == 2) {
return TRUE; /* special case */
} else {
return isPrime(a); /* works only for odd a */
}
4.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;
//}
4.2 文檔注釋(Documentation Comments)
注意：此處描述的注釋格式之范例，參見"Java源文件范例"
若想了解更多，參見"How to Write Doc Comments for Javadoc"，其中包含了有關文檔注釋標記的信息(@return, @param, @see)：http://java.sun.com/javadoc/writingdoccomments/index.html
若想了解更多有關文檔注釋和javadoc的詳細資料，參見javadoc的主頁： http://java.sun.com/javadoc/index.html
文檔注釋描述Java的類、接口、構造器，方法，以及字段(field)。每個文檔注釋都會被置於注釋定界符/**...*/之中，一個注釋對應一個類、接口或成員。該注釋應位於聲明之前：
/**
* The Example class provides ...
*/
public class Example { ...
注意頂層(top-level)的類和接口是不縮進的，而其成員是縮進的。描述類和接口的文檔注釋的第一行(/**)不需縮進；隨后的文檔注釋每行都縮進1格(使星號縱向對齊)。成員，包括構造函數在內，其文檔注釋的第一行縮進4格，隨后每行都縮進5格。
若你想給出有關類、接口、變量或方法的信息，而這些信息又不適合寫在文檔中，則可使用實現塊注釋或緊跟在聲明后面的單行注釋。例如，有關一個類實現的細節，應放入緊跟在類聲明后面的實現塊注釋中，而不是放在文檔注釋中。
文檔注釋不能放在一個方法或構造器的定義塊中，因為Java會將位於文檔注釋之后的第一個聲明與其相關聯。
- 頂
- 0