注釋規(guī)范

別給糟糕的代碼加注釋——重新寫吧

• 注釋的恰當(dāng)用法是彌補(bǔ)我們?cè)谟么a表達(dá)意圖時(shí)遭遇的失敗。

注釋會(huì)撒謊

• 注釋存在的時(shí)間越久，就離其所描述的代碼越遠(yuǎn)。
• 代碼在變動(dòng)，然而注釋并不總是隨之變動(dòng)。

寫注釋要記住的要點(diǎn)

• 注釋不能美化糟糕的代碼。與其花時(shí)間編寫解釋你寫出的糟糕代碼的注釋，還不如清潔那些糟糕的代碼。
• 用代碼來闡述，使變量名更易懂。

好的注釋

• 提供信息的注釋。例如解釋某個(gè)抽象方法的返回值，規(guī)定參數(shù)的順序和個(gè)數(shù)。
• 對(duì)意圖的解釋。使別人更清楚一段復(fù)雜代碼是在干什么。
• 法律信息。在每個(gè)源文件開頭，寫上版權(quán)時(shí)間等法律信息。

常見的注釋（重要）

• 闡釋。把一些難懂的參數(shù)和返回值的意義翻譯成某種可讀形式。
• 警示。比如說有一個(gè)函數(shù)，測(cè)試它將會(huì)花上很多時(shí)間，我們將寫上警示。
• 放大重要性。就是可以用來放大某處(看起來不合理)的重要性。
• TODO，大部分ide會(huì)識(shí)別定位TODO注釋。如果有寫TODO的習(xí)慣，要定期查看。

壞注釋

通常，壞注釋都是糟糕的代碼的支撐和借口，或者對(duì)錯(cuò)誤決策的修正。

• 注釋掉的代碼。注釋后的代碼會(huì)嚴(yán)重誤導(dǎo)以后別人閱讀這段代碼，在早已有版本控制系統(tǒng)的時(shí)代，系統(tǒng)會(huì)將之前版本的代碼記錄，而無需我們用注釋來標(biāo)記，所以被注釋掉的代碼應(yīng)該全部刪掉。
• 為了解釋復(fù)雜語(yǔ)句的注釋。當(dāng)一行語(yǔ)句很復(fù)雜的時(shí)候，我們通常會(huì)寫注釋。但實(shí)際上規(guī)范的寫法是，一個(gè)語(yǔ)句只做一件簡(jiǎn)單的事，我們應(yīng)該重構(gòu)原來的復(fù)雜語(yǔ)句，改成幾行簡(jiǎn)單語(yǔ)句，從而代替注釋。
• 喃喃自語(yǔ)。任何注釋如果要迫使讀者查看其它模塊的注釋和代碼，就是沒能與讀者溝通好，這樣的代碼不值得去寫。就像喃喃自語(yǔ)一樣，并沒有它的真正。
• 多余的注釋。當(dāng)注釋沒有證明代碼的意義，也沒有給出代碼的意圖和邏輯，它并不比讀代碼更容易的時(shí)候，這種注釋，多半是多余的。他不如代碼精確，會(huì)誤導(dǎo)讀者接受不精確的信息，而不能正確的理解代碼。
• 誤導(dǎo)性注釋。有的時(shí)候注釋缺少一些信息，會(huì)誤導(dǎo)程序員，使得其他人簡(jiǎn)單的調(diào)用某個(gè)函數(shù)，哦，缺少的信息，很可能導(dǎo)致程序員陷入調(diào)試的困境之中。