JAVA程式設計規範之注釋規約

一、規範存在的意義

應用編碼規範對于軟體本身和軟體開發人員而言尤為重要，有以下幾個原因：

1、好的編碼規範可以盡可能的減少一個軟體的維護成本 , 并且幾乎沒有任何一個軟體，在其整個生命周期中，均由最初的開發人員來維護；

2、好的編碼規範可以改善軟體的可讀性，可以讓開發人員盡快而徹底地了解新的代碼；

3、好的編碼規範可以最大限度的提高團隊開發的合作效率；

4、長期的規範性編碼還可以讓開發人員養成好的編碼習慣，甚至鍛煉出更加嚴謹的思維；

二、注釋規約

1、【強制】類、類屬性、類方法的注釋必須使用 Javadoc 規範，使用​

​/**内容*/格式，不得使用 //xxx 方式​

​。

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

閱讀效率。

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

3、【強制】所有的類都必須添加建立者和建立日期。

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

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

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

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

8、【參考】合理處理注釋掉的代碼。在上方詳細說明，而不是簡單的注釋掉。如果無用，則删除。

9、【參考】對于注釋的要求: 第一、能夠準确反應設計思想和代碼邏輯；第二、能夠描述業務含義，使别的程式員能夠迅速了解到代碼背後的資訊。完全沒有注釋的大段代碼對于閱讀者形同天書，注釋是給自己看的，即使隔很長時間，也能清晰了解當時的思路；注釋也是給繼任者看的，使其能夠快速接替自己的工作。

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

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