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