JAVA編程規範-註釋規範

1.【強制】類、類屬性、類方法的註釋必須使用 Javadoc規範，使用/**內容*/格式，不得使用
//xxx方式。
說明：在 IDE編輯窗口中，Javadoc方式會提示相關注釋，生成 Javadoc能夠正確輸出相應注
釋；在 IDE中，工程調用方法時，不進入方法便可懸浮提示方法、參數、返回值的意義，提升
閱讀效率。

2.【強制】全部的抽象方法（包括接口中的方法）必需要用 Javadoc註釋、除了返回值、參數、
異常說明外，還必須指出該方法作什麼事情，實現什麼功能。
說明：對子類的實現要求，或者調用注意事項，請一併說明。

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） 待辦事宜（TODO）:（ 標記人，標記時間，[預計處理時間]）
表示須要實現，但目前還未實現的功能。這其實是一個 Javadoc的標籤，目前的 Javadoc
尚未實現，但已經被普遍使用。只能應用於類，接口和方法（由於它是一個 Javadoc標籤）。

2） 錯誤，不能工做（FIXME）:（標記人，標記時間，[預計處理時間]）
在註釋中用 FIXME標記某代碼是錯誤的，並且不能工做，須要及時糾正的狀況。