註記規約

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

說明：在IDE 編輯視窗中， Javadoc 方式會提示相關註釋，產生Javadoc 可以正確輸出對應註釋； 在IDE 中，工程呼叫方法時，不進入方法即可懸浮提示方法、參數、回傳值的意義，提高#閱讀效率。

2. 【強制】所有的抽象方法（ 包含介面中的方法） 必須要用Javadoc 註解、除了傳回值、參數、異常說明外，還必須指出該方法做什麼事情，實現什麼功能。

說明：對子類別的實作要求，或呼叫注意事項，請一併說明。

3. 【強制】所有的類別都必須加入創建者資訊。

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

5. 【強制】所有的枚舉型別欄位必須要有註釋，說明每個資料項的用途。

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

反例：“ TCP 連線逾時”解釋成“傳輸控制協定連線逾時”，理解反而費腦筋。

7. 【建議】程式碼修改的同時，註解也要進行對應的修改，尤其是參數、傳回值、例外、核心邏輯等的修改。

說明：程式碼與註解更新不同步，就像路網與導航軟體更新不同步一樣，如果導航軟體嚴重滯後，就失去了導航的意義。

8. 【參考】註解掉的程式碼盡量要配合說明，而不是簡單的註解掉。

說明：程式碼被註解掉有兩種可能性：1 ） 後續會恢復此段程式碼邏輯。 2 ） 永久不用。前者如果沒有備註訊息，難以知曉註釋動機。後者建議直接刪掉 （ 程式碼倉庫保存了歷史代碼 ） 。

9. 【參考】對於註解的要求：第一、能夠準確反應設計思想和程式碼邏輯； 第二、能夠描述業務含義，使別的程式設計師能夠迅速了解到程式碼背後的訊息。完全沒有註釋的大段代碼對於閱讀者形同天書，註釋是給自己看的，即使隔很長時間，也能清晰理解當時的思路； 註釋也是給繼任者看 的，使其能夠快速接替自己的工作。

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

反例：

// put elephant into fridge
put(elephant, fridge);

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

11. 【參考】特殊註解標記，請註明標記人與標記時間。注意及時處理這些標記，透過標記掃描，經常清理此類標記。線上故障有時候就是來自這些標記處的程式碼。

1 ） 待辦事宜（TODO） : （標記人，標記時間， [ 預計處理時間]）

表示需要實現，但目前還未實現的功能。這其實是一個 Javadoc 的標籤，目前的 Javadoc#還沒有實現，但已經被廣泛使用。只能應用於類，介面和方法 （ 因為它是一個 Javadoc 標籤 ） 。

2 ) 錯誤，不能工作（FIXME） : （標記人，標記時間， [ 預計處理時間]）

在註解中用FIXME 標記某程式碼是錯誤的，而且不能工作，需要及時糾正的情況。