阿裡發佈了<<阿裡巴巴Java開發手冊終極版>>，也許看過後也不能完全吸收，我在這裡分類整理，方便大家在手機端查看，一起學習阿裡對Java工程師編程的規約。 註釋規約 1. 【強制】類、類屬性、類方法的註釋必須使用 Javadoc 規範，使用/**內容*/格式，不得使用// xxx 方式。 說明：在 ...
阿裡發佈了<<阿裡巴巴Java開發手冊終極版>>，也許看過後也不能完全吸收，我在這裡分類整理，方便大家在手機端查看，一起學習阿裡對Java工程師編程的規約。
註釋規約
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 標記某代碼是錯誤的，而且不能工作，需要及時糾正的情況。
