有人說，代碼即注釋，也就是通過你的代碼就能看得懂你的代碼邏輯是什么。但是對於大多數人來說，這有些不切實際，每個公司的研發團隊成員的能力是不一樣的，有的能力強，有的能力弱，能力強的體現在能解決若干問題，但是在編碼規范方面卻有待提高，能力弱的，有的能力弱的在代碼規范方面卻比所謂的能力強的要好得多，這里的”能力強”並不是指兩個人的聰明才智差異很大，而是指特定領域的積累，有的積累得多，經驗豐富，有的積累的少，經驗不那么豐富。但因為是一個團隊，就必須要有一定的約束，不僅僅是對能力強的，能力差也一樣，一視同仁，團隊不能搞單兵作戰，那樣就失去了團隊的意義。
近來我不斷思考一件事情，如何將代碼注釋寫的更好，過去待了好幾家公司，我寫代碼對於注釋的態度如下:
- (1)有時間就寫，沒時間后面再說(實際等於不寫任何注釋)；
- (2)針對特定接口、類、方法寫一些概要注釋(也就是解釋該接口、類、方法是做什么的)；
- (3)針對復雜的邏輯，寫注釋，自上而下。
但是最終做的最多的還是(1)，哪怕有的時候工作中有一定的空閑時間，我所想的並不是如何將以往沒寫注釋的補充一下注釋，而是了解研究現在的新技術(流行的編程語言或Java相關的框架組件等)。
這樣做的最后結果是，代碼可讀性越來越差，可讀性差導致的擴展性也就越來越差，可讀性跟可擴展性有一定的相關性。
舉個例子:
在開發時間緊迫的時候，面對新的功能，看到以往有類似的功能，通常我們的做法是將其復制過來，改了一些，測試了一下，功能輸出結果，符合預期，然后就不管了，下次再遇到類似的功能，仍然采取該做法。突然某一天，經理說這個新的功能里面要加一些附加小功能，並同時跟這個類似的都全部加上，由於我們之前習慣了復制黏貼，這時對於我們無疑是毀滅性打擊，只能拼命加班加點弄了(從這一刻，我明白了碼農是如何養成的)。
假設我們有這樣一個習慣，面對重復兩次或三次以上的功能代碼，我們可將其抽取成一個通用方法(針對類似的功能)，一方面，代碼可重用性增強，另一方面減少不必要的代碼量，最后一方面，未來如果需要加擴展，我們只需改動這一個方法即可，同時我們寫注釋，將這一方法寫清楚即可。最近我迫使自己養成這樣的一個習慣，面對好幾個功能模塊，我發現輕松了很多，工作效率也大大提升。
一、回歸正題，從我的理解上，注釋該怎么寫？
- (1)復雜的邏輯應有一個流程圖(可以是visor圖、也可以是txt或word、思維導圖等)，按照流程圖在對應的代碼上寫下注釋；
- (2)接口、類、方法都需要寫注釋(這個注釋通常包含作者、時間、描述等通用，可通過IDEA模板實現)，針對特定的方法，最好使用多行注釋，按照數字順序進行列舉；
- (3)參考開源項目是如何寫注釋的(如Java、Spring全家桶相關的框架等)；
- (4)方法內部邏輯上，盡量減少注釋，如果方法內部邏輯太長，一大堆注釋，像寫作文似的，改一個地方，需要整體看一遍，結合(1)和(2)或(2)。
二、那么從阿里巴巴Java開發手冊上對於注釋又是怎么描述的？
1.【強制】類、類屬性、類方法的注釋必須使用 Javadoc 規范，使用/*內容/格式，不得使用// xxx 方式。
說明：在 IDE 編輯窗口中，Javadoc 方式會提示相關注釋，生成 Javadoc 可以正確輸出相應注釋；在 IDE 中，工程調用方法時，不進入方法即可懸浮提示方法、參數、返回值的意義，提高
閱讀效率。
2. 【強制】所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋、除了返回值、參數、異常說明外，還必須指出該方法做什么事情，實現什么功能。
說明：對子類的實現要求，或者調用注意事項，請一並說明。
3. 【強制】所有的類都必須添加創建者和創建日期。
4. 【強制】方法內部單行注釋，在被注釋語句上方另起一行，使用//注釋。方法內部多行注釋使用/ /注釋，注意與代碼對齊。
5. 【強制】所有的枚舉類型字段必須要有注釋，說明每個數據項的用途。
6. 【推薦】與其“半吊子”英文來注釋，不如用中文注釋把問題說清楚。專有名詞與關鍵字保持英文原文即可。
反例：“TCP 連接超時”解釋成“傳輸控制協議連接超時”，理解反而費腦筋。
7. 【推薦】代碼修改的同時，注釋也要進行相應的修改，尤其是參數、返回值、異常、核心邏輯等的修改。
說明：代碼與注釋更新不同步，就像路網與導航軟件更新不同步一樣，如果導航軟件嚴重滯后，就失去了導航的意義。
8. 【參考】謹慎注釋掉代碼。在上方詳細說明，而不是簡單地注釋掉。如果無用，則刪除。
說明：代碼被注釋掉有兩種可能性：1）后續會恢復此段代碼邏輯。2）永久不用。前者如果沒有備注信息，難以知曉注釋動機。后者建議直接刪掉（代碼倉庫保存了歷史代碼）。