編碼規約之注釋規約

目錄

一、強制

1.類、類屬性、類方法的注釋必須使用 Javadoc 規範

2.所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋

3.所有的類都必須添加建立者和建立日期

4.方法内部單行注釋使用//注釋

5.所有的枚舉類型字段必須要有注釋

二、推薦

1.注釋中英文問題

2.代碼修改的同時要修改相應注釋

三、參考

1.謹慎注釋掉代碼

2.對于注釋的要求

3.避免過多過濫的注釋

4.特殊注釋标記

一、強制

1.類、類屬性、類方法的注釋必須使用 Javadoc 規範

類、類屬性、類方法的注釋必須使用 Javadoc 規範，使用格式，不得使用 // xxx 方式。

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

2.所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋

所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋、除了傳回值、參數、 異常說明外，還必須指出該方法做什麼事情，實作什麼功能。

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

3.所有的類都必須添加建立者和建立日期

4.方法内部單行注釋使用//注釋

方法内部單行注釋，在被注釋語句上方另起一行，使用//注釋。方法内部多行注釋使用注釋，注意與代碼對齊。

5.所有的枚舉類型字段必須要有注釋

所有的枚舉類型字段必須要有注釋，說明每個資料項的用途。 

二、推薦

1.注釋中英文問題

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

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

2.代碼修改的同時要修改相應注釋

代碼修改的同時，注釋也要進行相應的修改，尤其是參數、傳回值、異常、核心邏輯 等的修改。

說明：代碼與注釋更新不同步，就像路網與導航軟體更新不同步一樣，如果導航軟體嚴重滞後， 就失去了導航的意義。

三、參考

1.謹慎注釋掉代碼

謹慎注釋掉代碼，在上方詳細說明，而不是簡單地注釋掉。如果無用，則删除。

說明：代碼被注釋掉有兩種可能性：

1）後續會恢複此段代碼邏輯

2）永久不用。前者如果沒有備注資訊，難以知曉注釋動機。後者建議直接删掉（代碼倉庫儲存了曆史代碼）

2.對于注釋的要求

第一、能夠準确反應設計思想和代碼邏輯；

第二、能夠描述業務含義，使别的程式員能夠迅速了解到代碼背後的資訊。完全沒有注釋的大段代碼對于閱讀者形同 天書，注釋是給自己看的，即使隔很長時間，也能清晰了解當時的思路；注釋也是給繼任者看的，使其能夠快速接替自己的工作。

3.避免過多過濫的注釋

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

反例：

// put elephant into fridge

put(elephant, fridge);

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

4.特殊注釋标記

特殊注釋标記，請注明标記人與标記時間。注意及時處理這些标記，通過标記掃描， 經常清理此類标記。線上故障有時候就是來源于這些标記處的代碼。

1） 待辦事宜（TODO）:（ 标記人，标記時間，[預計處理時間]） 表示需要實作，但目前還未實作的功能。這實際上是一個 Javadoc 的标簽，目前的 Javadoc 還沒有實作，但已經被廣泛使用。隻能應用于類，接口和方法（因為它是一個 Javadoc 标簽）。

2） 錯誤，不能工作（FIXME）:（标記人，标記時間，[預計處理時間]） 在注釋中用 FIXME 标記某代碼是錯誤的，而且不能工作，需要及時糾正的情況。