“別給糟糕的代碼加注釋——重新寫吧。”
? ? ? ? ? ? ? ? ? ? ? ? ? ——Brian W.Kernighan 與 P.J.Plaugher
注釋的恰當用法是彌補我們在用代碼表達意圖時遭遇的失敗。所以注釋并不是一種好東西，當我們要寫注釋時，應想辦法找找能不能翻盤，從而使我們不通過注釋就能表達清晰意圖。
注釋不能美化糟糕代碼
我們寫注釋的動機之一是糟糕代碼的存在。想通過注釋來使之表意清晰。
但是請記住，帶有少量注釋的整潔而有表達力的代碼，要比代有大量注釋的零碎而復雜的代碼像樣的多。所以與其花時間為糟糕的代碼寫注釋。不如花時間將它重構。
用代碼來闡述
// check to see if the employee is eligible for full benefits
if ( (employee.flags & HOURLY_FLAG) && (employee.age > 65) )
//VS
if (employee.isEligibleForFullBenefits())
我們看上面兩個指令：一個通過注釋來表達意圖，而另一個創建了一個函數，但表達了相同的意思，而我們只需思考幾秒
好注釋
有些注釋時好的，也是有利的。下面是一些比較值得寫的注釋。但是請記住，真正好的注釋時想辦法不去寫的注釋。
- 法律信息
公司代碼規范要求編寫的與法律相關的注釋。
如果可以，這種注釋應指向一份標準許或其他外部文檔，而不是把條款放在注釋中 - 提供信息的注釋
有時用注釋來提供基本信息也有其作用 - 對意圖的解釋
注釋不僅提供了有關實現的有用信息，而且提供了某個決定后面的意圖。 - 闡釋
注釋把某些晦澀難明的參數或返回值的意義翻譯為某種可讀形式。 - 警示
用于警告別的程序員會出現某種后果的注釋。 - TODO注釋
TODO是一種程序員認為應該做，但由于某些原因目前還未做的工作。
TODO要定期查看，刪除不需要的 - 放大
注釋可以用來放大某種看起來不合理之物的重要性。 - 公共API的Javadoc
壞注釋
通常，壞注釋都是糟糕代碼的支撐或借口，或者對錯誤決策的修正。
- 喃喃自語
只是覺得應該添加或者過程需要就加注釋。 - 多余的注釋
不要讓讀注釋的時間比讀代碼的時間還長。 - 誤導性注釋
雖然初衷是好的，但是寫的不夠精確地注釋。 - 循規式注釋
為函數或者變量加注釋是愚蠢和可笑的。 - 日志式注釋
記錄每次修改的日志 - 廢話注釋
顧名思義，純粹在講廢話的注釋 - 可怕的廢話
不知道干什么，只是隨意的復制粘貼 - 能用函數名或變量時就別用注釋
- 位置標記
用于標記某個特殊位置 - 括號后面的注釋
適用于深度嵌套結構的長函數，不適用于短小、封裝的函數。 - 歸屬與署名
源代碼控制系統非常善于記住是誰在何時添加了什么。所以不比較自己增加簽名
12.注釋掉的代碼
沒用的代碼直接刪掉，而不是注釋。不然別人都不知道這段代碼到底有沒有用。
13.HTML注釋 - 非本地信息
- 信息過多
- 不明顯的聯系
- 函數頭
- 非公共代碼中的javadoc
