1.8 註釋規約

1.強制：類、類屬性、類方法的註釋必須使用 Javadoc 規範，使用 /** 內容 */ 格式，不得使用 // xxx 方式。

說明：

        在 IDE 編輯窗口中，Javadoc 方式會提示相關注釋，生成 Javadoc 可以正確輸出相應註釋；在 IDE 中，當遠程調用方法是，不進入方法即可懸浮提示方法、參數、返回值得意義，提高閱讀效率。

2.強制：所有抽象方法（包括接口中的方法）必須要用 Javadoc 可以正確輸出相應註釋；在 IDE 中，當工程調用方法時，不進入方法即可懸浮提示方法、參數、返回值的意義，提高閱讀效率。

說明：

        對子類的實現要求，或者調用注意事項，請一併說明。

3.強制：所有的類必須添加創建者和創建日期。

4.強制：方法內部的單行註釋，在被註釋語句上方另起一行，使用 // 註釋。方法內部的多行註釋，使用 /* */ 註釋，注意與代碼對齊。

5.強制：所有的枚舉類型字段必須要有註釋，說明每個數據項的用途。

6.推薦：與其用“半吊子”英文來註釋，不如用中文註釋把問題說清楚。專有名詞與關鍵字保持英文原文即可。

反例：

        將“TCP連接超時” 解釋成 “傳輸控制協議連接超時”，理解起來反而費腦筋。

7.推薦：在修改代碼的同時，要對註釋進行相應的修改，尤其是參數、返回值、異常、核心邏輯等的修改。

說明：

        代碼與註釋更新不同步，就像路網與導航軟件更新不同步一樣，如果導航軟件更新眼中滯後，就失去了導航的意義。

8.參考：謹慎註釋掉代碼。要在上方詳細說明，而不是簡單的註釋掉。如果無用，則刪除。

說明：

        代碼被註釋掉有兩種可能性。

1. 後續會恢復此段代碼邏輯。
2. 永久不用。

        前者如果沒有備註信息，難以知曉註釋動機，後者建議直接刪掉（代碼倉庫中保存了歷史代碼）。

9.參考：對註釋的要求：

1. 能夠準確的反映設計思想和代碼邏輯。
2. 能夠描述業務含義，使其他程序員能夠迅速瞭解代碼背後的信息。完全沒有註釋的大段代碼對於閱讀者形同天書；註釋是給自己看的，應做到及時間隔很長時間，也能清晰理解當時的思路；註釋也是給繼任者看的，使其能夠快速接替自己的工作。

10.參考：好的命名、代碼結構是自解釋的，註釋力求精簡準確、表達到位。避免出現註釋的一個極端；過多過濫的註釋，因爲代碼的邏輯一旦修改，修改註釋是相當大的負擔。

反例：

        // put elephant into fridge

        put (elephant fridge);

說明：

        方法名 put ，加上兩個有意義的變量名 elephant 和 fridge ，已經說明這是在幹什麼了。語義清晰的代碼不需要額外的註釋。

11.參考：特殊註釋標記，請註明標記人和標記時間。注意及時處理這些標記，通過標記掃描經常清理此類標記。有時候線上故障就來源於這些標記處的代碼。

1. 待辦事宜（ TODO0 ）：（標記人，標記時間，【預計處理時間】）表示需要實現，但目前還未實現的功能。這實際上是一個 Javadoc 的標籤，雖然目前還未實現，但已經被廣泛使用，且只能應用於類、接口和方法（因爲它是一個 Javadoc 標籤）。
2. 錯誤，不能工作（FIXME）:（標記人，標記時間，【預計處理時間】）在主時鐘用 FIXME 標記某代碼是錯誤的，而且不能工作，需要及時糾正。