Java 程式碼慣例 -- 第五章 註解

5. 註解

Java 程式可以有兩種註解：實作註解和文件註解。實作註解是可以在 C++ 中看的到
，以 /*...*/ 和 // 分隔的。文件註解(又稱為 "doc 註解")是只有 Java 有，
而且是用 /**...*/ 分隔的。doc 註解可以被用 javadoc 工具萃取成 HTML 檔案
。

實作註解是用來將程式碼註解掉或是說關於特定實作。doc 註解是要描述程式碼的規格
，必須以要讓一個手上沒有原始碼的開發者閱讀的實作不相關的觀點來寫。

註解應該用來給予程式碼概觀，提供閱讀程式碼本身無法獲得的額外資訊。註解
應該只包含與閱讀和了解這程式有關的資訊。例如這一致的套件是如何被建立，或是
它存在於甚麼目錄都不應該被包含在註解中。

對不瑣碎和無法觀察到的設計決定的討論是適當的，但是避免在程式碼中出現重
複的資訊。冗長的註解太容易過期了。通常，避免任何程式碼改進後好像會過期
的註解。

注意：註解的頻率有時候反映出貧乏的程式碼品質。當你覺得必須強迫加入註解
時，請考慮重寫程式碼來讓它更清楚。

註解不應該被用星號或其他字元畫成的大格子包起來。
註解不能包含特殊字元，如 form-feed 和 backspace。





5.1 實作註解格式
1
程式可以有四種實作註解的型態：區塊，單行，尾隨，行結尾。





5.1.1 區塊註解

區塊註解用來提供檔案，方法，資料結構和演算法的描述。區塊註解可以用在
每一個檔案起始處，或是在每個方法前面。它們也可以用在其他的位置，如在
方法內部。在函式或方法內的區塊註解應該縮排到和他們描述的碼相同的層級。

區塊註解應該在前面有一行空白行，來將它與程式碼結構分離。

/*
* 這是區塊註解。
*/

區塊註解可以用 /*- 開始，這個在區塊註解起始不能重定格式時，會被當成是
縮排(1)。例如：

/*-
* 這裡是含有我想要 縮排(1) 去忽略的一些非常特別的格式。
*
* 一
* 二
* 三
*/

注意：如果你不使用縮排(1)，那你不需要在你的程式碼中使用 /*- 或是做其它
讓步來讓某些其它人可以在你的程式碼執行縮排(1)。

參考 5.2 "文件註解"。




5.1.2 單行註解

簡短的註解可以以縮排到和隨後的碼同樣層級的單行模式出現。如果註解無法寫
成單行，那他應該遵循區塊註解格式(參見 5.1.1 小節)。單行註解前面應該有
一空白行。這是 Java 程式碼的單行註解範例：

if (condition) {

/* 處理這個狀況。 */
...
}




5.1.3 尾隨註解

非常短的註解可以在他們描述的程式碼同一行出現，但是應該離開足夠的距離
來讓他們與敘述分隔。如果有超過一個短註解在大區塊程式碼中出現，那他們
應該被縮排到同一個 tab 設定。

這裡是一個 Java 程式碼中的尾隨註解範例：

if (a == 2) {
return TRUE; /* 特別狀況 */
} else {
return isPrime(a); /* 只在 a 為奇數時有作用 */
}



5.1.4 行結尾註解

這 // 的註解分隔子可以註解一整行或是行的一部分。他不能用在連貫的多行
文字註解中；但是他可以用在連貫的多行中來註解掉一區塊的程式碼。下列是
這三種形式的範例：

if ( foo > 1) {

// 做出雙空翻。
...
}
else {
return false; // 在這裡解釋為甚麼。
}


// if (bar > 1) {
//
// // 做三重空翻。
// ...
//}
//else{
// return false;
//}





5.2 文件註解

注意：參考 11.1 "Java 原始碼檔案範例" 來看這邊描述的註解格式範例。

進一步的細節請看包含 doc 註解標籤(@return, @param, @see) 資訊的
"How to Write Doc Comments for JavaDoc"：

http://java.sun.com/products/jdk/javadoc/writingdoccomments.html

進一步的 doc 註解和 javadoc 細節，請看 javadoc 首頁：

http://java.sun.com/products/jdk/javadoc/

doc 註解描述了 Java 類別, 介面, 建構子，方法，和欄位。每一個 doc 註解
都設定成放在 /**...*/ 分隔子中，每一個類別，介面或是成員都有一個註解。
這些註解應該就在在宣告的前面出現。

/**
* 這個 Example 類別提供了 ...
*/
public class Exampke { ...

注意頂層的類別和介面並沒有縮排，而他們的成員有。這類別和介面的 doc 註解
的第一行(/**)是沒有縮排的；隨後的 doc 註解行都有 1 個縮排的空格 ( 垂直
對齊星號)。成員 (包括建構子) 的第一個 doc 註解行則有 4 個空白，以及之後的
有五個空白。

如果你需要給予不適合出現在文件中的關於類別，介面，變數，或是方法的資訊，
使用馬上接在宣告之後的區塊註解(見 5.1.1 小節)或是單行註解(見 5.1.2 小節)
來實作。例如，關於類別實作的細節應該在跟著類別敘述的區塊註解實作中，而不
是在類別的 doc 註解中。

doc 註解不應該被放在方法或是建構子的定義區塊中，因為 Java 會將文件註解
和註解後的第一個宣告關聯起來。