《阿里Java開發手冊》 | 編程規約 - 註解規約
【強制】類、類屬性、類方法的註解必須使用 Javadoc 規範，使用/**內容*/格式，不得使用 // xxx 方式。
說明：在 IDE 編輯窗口中，Javadoc 方式會提示相關註解，生成 Javadoc 可以正確輸出相應註解；在 IDE 中，工程調用方法時，不進入方法即可懸浮提示方法、參數、返回值的意義，提高閱讀效率。
【強制】所有的抽象方法(包括接口中的方法)必須要用 Javadoc 註解、除了返回值、參數、異常說明外，還必須指出該方法做什麼事情，實作什麼功能。
說明：對子類的實作要求，或者調用注意事項，請一併說明。
【強制】所有的類都必須添加建立者和建立日期。
說明：在設置模板時，注意 IDEA 的 @author 為`${USER}`，而 eclipse 的 @author 為`${user}`，大小寫有區別，而日期的設置統一為 yyyy/MM/dd 的格式。
正例：
1 | /** |
【強制】方法內部單行註解，在被註解語句上方另起一行，使用//註解。方法內部多行註解使用/* */註解，注意與程式碼對齊。
【強制】所有的枚舉類型欄位必須要有註解，說明每個資料項的用途。
【推薦】與其“半吊子”英文來註解，不如用中文註解把問題說清楚。專有名詞與關鍵字保持英文原文即可。
反例：“TCP 連接超時”解釋成“傳輸控制協議連接超時”，理解反而費腦筋。
【推薦】程式碼修改的同時，註解也要進行相應的修改，尤其是參數、返回值、異常、核心邏輯等的修改。
說明：程式碼與註解更新不同步，就像路網與導航軟體更新不同步一樣，如果導航軟體嚴重滯後，就失去了導航的意義。
【推薦】在類中刪除未使用的任何欄位和方法;在方法中刪除未使用的任何參數聲明與內部變數。
【參考】謹慎註解掉程式碼。在上方詳細說明，而不是簡單地註解掉。如果無用，則刪除。
說明：程式碼被註解掉有兩種可能性:
- 後續會恢復此段程式碼邏輯。
- 永久不用。前者如果沒有備註訊息，難以知曉註解動機。後者建議直接刪掉即可，假如需要查閱歷史程式碼，登錄程式碼倉庫即可。
【參考】對於註解的要求：第一、能夠準確反映設計思想和程式碼邏輯；第二、能夠描述業務含義，使別的工程師能夠迅速了解到程式碼背後的訊息。完全沒有註解的大段程式碼對於閱讀者形同天書，註解是給自己看的，即使隔很長時間，也能清晰理解當時的思路;註解也是給繼任者看的，使其能夠快速接替自己的工作。
【參考】好的命名、程式碼結構是自解釋的，註解力求精簡準確、表達到位。避免出現註解的一 個極端:過多過濫的註解，程式碼的邏輯一旦修改，修改註解是相當大的負擔。
反例：
1 | // put elephant into fridge |
方法名 put，加上兩個有意義的變數名 elephant 和 fridge，已經說明了這是在幹什麼，語義清晰的程式碼不
需要額外的註解。
【參考】特殊註解標記，請註明標記人與標記時間。注意及時處理這些標記，通過標記掃描， 經常清理此類標記。線上故障有時候就是來源於這些標記處的程式碼。
- 待辦事宜(TODO):(標記人，標記時間，[預計處理時間]) 表示需要實作，但目前還未實作的功能。這實際上是一個 Javadoc 的標籤，目前的 Javadoc 還沒有實作，但已經被廣泛使用。只能應用於類，接口和方法(因為它是一個 Javadoc 標籤)。
- 錯誤，不能工作(FIXME):(標記人，標記時間，[預計處理時間])
在註解中用 FIXME 標記某程式碼是錯誤的，而且不能工作，需要及時糾正的情況。
心得
看完這篇「註解規約」後，非常有感觸，當在維護別人撰寫的程式碼的時候，經常就是當天書在看，什麼註解什麼說明都沒有；最可怕的莫過於沒在使用的程式碼沒有做刪除；還有註解的說明跟程式碼完全對不上或是邏輯相反⋯。
只能說在維護註解是個成本，但是這些註解絕對是在日後維護或是功能再次開發會有很大幫助的。
結語
文章越看越多，技術越學越多，就會發現自己的不足；技術學到後面都會想要將基礎再重新在打得更加扎實。
以前在開發覺得理所當然的事情，例如：命名規則、命名規範，照著別人怎麼說就怎麼做的想法，並沒有好好去想為什麼要這樣設計和規範。
於是乎同事們推薦《阿里巴巴Java開發手冊》來做閱讀，書中提到種種規範《正確範例》、《錯誤範例》還有解釋定義說明；我相信在閱讀完這一系列後，一定會更加扎實且實在。
如對此書有興趣，建議去購買官方認證的書籍，給予官方支持。
註：如有侵權，通知即刪。
註：以上參考了
Alibaba-Java-Coding-Guidelines Github
Alibaba-Java-Coding-Guidelines English Version
