1.【強制】類、類屬性、類方法的注釋必須使用 Javadoc 規(guī)范，使用 /** 內容 */ 格式，不得使用 // xxx 方式。
說明：在 IDE 編輯窗口中，Javadoc 方式會提示相關注釋，生成 Javadoc 可以正確輸出相應注釋；在 IDE 中，工程調用方法時，不進入方法即可懸浮提示方法、參數(shù)、返回值的意義，提高閱讀效率。
2.【強制】所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋、除了返回值、參數(shù)異常說明外，還必須指出該方法做什么事情，實現(xiàn)什么功能。
說明：對子類的實現(xiàn)要求，或者調用注意事項，請一并說明。
3.【強制】所有的類都必須添加創(chuàng)建者和創(chuàng)建日期。
說明：在設置模板時，注意 IDEA 的 @author 為${USER}，而 eclipse 的@author 為${user}，大小寫有區(qū)別，而日期
的設置統(tǒng)一為 yyyy/MM/dd 的格式。
正例：
/**
*
* @author yangguanbao
* @date 2021/11/26
*
**/
4.【強制】方法內部單行注釋，在被注釋語句上方另起一行，使用 // 注釋。方法內部多行注釋使用 /* */
注釋，注意與代碼對齊。
5.【強制】所有的枚舉類型字段必須要有注釋，說明每個數(shù)據(jù)項的用途。
6.【推薦】與其用半吊子英文來注釋，不如用中文注釋說清楚。專有名詞與關鍵字保持英文原文即可。
反例：“TCP 連接超時”解釋成“傳輸控制協(xié)議連接超時”，理解反而費腦筋。
7.【推薦】代碼修改的同時，注釋也要進行相應的修改，尤其是參數(shù)、返回值、異常、核心邏輯等。
說明：代碼與注釋更新不同步，就像公路網(wǎng)與導航軟件更新不同步一樣，如果導航軟件嚴重滯后，就失去了導航的意義。
8.【推薦】在類中刪除未使用的任何字段和方法、內部類；在方法中刪除未使用的參數(shù)聲明與內部變量。
9.【參考】謹慎注釋掉代碼。在上方詳細說明，而不是簡單地注釋掉。如果無用，則刪除。
說明：代碼被注釋掉有兩種可能性：1）后續(xù)會恢復此段代碼邏輯。2）永久不用。前者如果沒有備注信息，難以知曉注釋動機。后者建議直接刪掉即可，假如需要查閱歷史代碼，登錄代碼倉庫即可。
10.【參考】對于注釋的要求：第一、能夠準確反映設計思想和代碼邏輯；第二、能夠描述業(yè)務含義，使別的程序員能夠迅速了解到代碼背后的信息。完全沒有注釋的大段代碼對于閱讀者形同天書，注釋是給自己看的，即使隔很長時間，也能清晰理解當時的思路；注釋也是給繼任者看的，使其能夠快速接替自己的工作。
11.【參考】好的命名、代碼結構是自解釋的，注釋力求精簡準確、表達到位。避免出現(xiàn)注釋的另一個極端：過多過濫的注釋，代碼的邏輯一旦修改，修改注釋又是相當大的負擔。
反例：
// put elephant into fridge
put(elephant, fridge);
方法名 put，加上兩個有意義的變量名稱 elephant 和 fridge，已經說明了這是在干什么，語義清晰的代碼不需要額外的注釋。
12.【參考】特殊注釋標記，請注明標記人與標記時間。注意及時處理這些標記，通過標記掃描，經常清理此類標記。線上故障有時候就是來源于這些標記處的代碼。
1）待辦事宜（TODO）：（標記人，標記時間，[預計處理時間]）表示需要實現(xiàn)，但目前還未實現(xiàn)的功能。這實際上是一個 Javadoc 的標簽，目前的 Javadoc 還沒有實現(xiàn)，但已經被廣泛使用。只能應用于類，接口和方法（因為它是一個Javadoc 標簽）。
2）錯誤，不能工作（FIXME）：（標記人，標記時間，[預計處理時間]）在注釋中用 FIXME 標記某代碼是錯誤的，而且不能工作，需要及時糾正的情況。
參考
- 2022 Java開發(fā)手冊(黃山版).pdf
- 白話阿里巴巴Java開發(fā)手冊（安全規(guī)約） - 李艷鵬 - 簡書(http://www.itdecent.cn/p/9528c4ea1504)
