多年來，我非常榮幸能和一些謙遜的公司和客戶合作。我也因此有機(jī)會接觸到各種不同的程序員—— 每個(gè)程序員都有自己獨(dú)特的風(fēng)格。事實(shí)上，每個(gè)項(xiàng)目本身都有一些獨(dú)特的元素。

這些特質(zhì)的交叉讓我去思考我曾經(jīng)審查、更新或提高過的程序代碼。與其說是代碼的實(shí)際邏輯，還不如說是開發(fā)人員自己添加到代碼中的注釋，對代碼產(chǎn)生了頗為深遠(yuǎn)的影響。這篇文章的主題就是羅列一些我印象深刻的一些代碼注釋。

因?yàn)镃arol讓我這么做

我記得審查程序代碼時(shí)，有一條注釋是這樣寫的：

// Because Carol Told Me to Do This 

在閱讀這行代碼時(shí)，我一下子就懵了，“誰是Carol？”以及“Carol讓這個(gè)開發(fā)人員做什么了？”雖然寫代碼的程序員知道這兩個(gè)答案，但換做是一個(gè)局外人或者是一個(gè)后面加進(jìn)來的人，那么這條注釋就毫無價(jià)值。當(dāng)我和我的經(jīng)理說起這條注釋的時(shí)候，他哈哈大笑，只是說了句Carol明顯是一個(gè)人名字之后，就無下文了。好吧，直到現(xiàn)在，我依然不知道這句注釋究竟是什么意思。

很大一部分被代碼遮擋

在另一種情況下，我相信我將問題范圍縮小到了一個(gè)特定的類。但是打開這個(gè)類，我看到大量的代碼被塊注釋掉了。讓人瘋狂的是，注釋的代碼是在方法的中間。所以，我只能在閱讀完頂部的代碼之后，滾動幾個(gè)屏幕，才能繼續(xù)閱讀剩下的代碼。你得牢記在心里，幸好中間間隔的時(shí)間不是太久，有到應(yīng)用程序的源代碼庫的鏈接。

在我心中，我對此非常嗤之以鼻，“提前閱讀沒有注釋的大塊代碼，卻只是看到了程序是用來做什么的”。當(dāng)我問另一名開發(fā)人員為什么代碼要像這樣被注釋和檢查的時(shí)候，他給我的回答是“萬一我們下次還要用到它呢”。我真心無語。

只是為了苦中作樂

在工作于一個(gè)基于web的應(yīng)用程序時(shí)，我發(fā)現(xiàn)了以下的JavaScript注釋：

// make sure it's correctly formatted, because in javascript things 
// like '7' or '4.3' or 'derpdy do 77' are valid dates 
// seriously, try it out for yourself: Date.parse('derpdy do 77') 

這里的開發(fā)人員意識到Date.parse（）方法存在著問題。為了警示他人，開發(fā)人員決定添加注釋作為警告，同時(shí)又苦中作樂了一番。我只能想象當(dāng)這個(gè)開發(fā)人員意識到此路不通時(shí)心中該是有多么的沮喪。

道歉

有些時(shí)候，程序員意識到他們的做法并不好。很多時(shí)候，這是基于開發(fā)小組之外所能做的唯一選擇。于是，出現(xiàn)了這樣的注釋：

// Sorry for what you are about to see 

閱讀代碼和理解實(shí)施方法背后的情況有助于完整地理解簡單的道歉式注釋。這有點(diǎn)像驚悚片里的英雄在采取有計(jì)劃的行動之前，先道歉的那一幕。

只圍繞它編碼

一開始作為一個(gè)白板聲明，最終被轉(zhuǎn)移到以下注釋：

// Doing this to "not do anything to effect Eric and Steve's code" 

基本上，這是一個(gè)進(jìn)程的入口點(diǎn)，代碼圍繞明顯由Eric和Steve引入的問題。但是我沒有任何相關(guān)的背景，也不認(rèn)識Eric和Steve，我只知道任何影響了他們的代碼都得禁止。

為了注釋而注釋

我們都聽過這樣一句話：“好的代碼是自文檔化的”。我完全同意這種說法，當(dāng)然有些注釋還是有必要的。但是，下面這種注釋，明顯不能劃到“必要”的范疇中：

return true; // returns true 

這種注釋確明顯是沒有必要的，因?yàn)槲覀兒苋菀桌斫夥祷厥裁?。我能想出的關(guān)于為什么要這么注釋的唯一原因就是，開發(fā)人員在添加到實(shí)際代碼前，使用注釋先制定出了方法，后來卻忘記刪掉這些注釋了。但是如果有代碼審查過程的話，就不會出現(xiàn)這樣的注釋。

注釋不正確

還記得前面提過的“好的代碼是自文檔化的”這句話嗎？那么，也許在所有注釋中，最糟糕的就是提供了錯(cuò)誤信息的注釋。請看下面這個(gè)簡單的例子：

// Always returns false 
public boolean isActive() { 
    return true; 
} 

現(xiàn)實(shí)中我所看到的例子遠(yuǎn)遠(yuǎn)沒有這么簡單。然而更糟糕的是，當(dāng)你需要依賴注釋寫一個(gè)復(fù)雜的方法時(shí)，才意識到這樣的注釋是無效的。在這種情況下沒有注釋都比錯(cuò)誤的注釋好。

小說般的注釋

***一種我見過的注釋是，開發(fā)人員寫的類似于小說般的注釋：

/** 
* This is the widget method which will process the list of 
* widgets from the widget controller and service in order to 
* handle pre-processing (where the widget information is 
* compared against the average widget history), actual 
* processing (where the quarterly, monthly and week attributes 
* are updated) and all of the post-processing (which include the 
* analytical metrics and audit table updates) aspects. It is 
* important to remember the widget rules around leap year where 
* the cost to transfer rate is 75% adjusted to the annual rate in 
* order to account for the extra day. When this happens, the 
* process will throw the LeapYearException which will need to be 
* validated by the application support staff. Failure to do so will 
* end up causing issues with the ME-4110 report. 
*/ 

我的經(jīng)驗(yàn)法則是，任何需要那么多信息的代碼或許應(yīng)該分解成更小的方法。而且注釋中這樣的信息應(yīng)該挪到實(shí)際的代碼之外。而在上面的例子中，像流水賬一樣記錄的業(yè)務(wù)規(guī)則和業(yè)務(wù)流程——卻有可能隨著時(shí)間而改變。

結(jié)論

關(guān)于如何正確地寫好代碼注釋，簡單地搜一下的話，網(wǎng)上有很多很多。有些甚至可能會告訴你如何盡可能地不在代碼中提供注釋。

相反，我想分享一些我有幸作為一個(gè)應(yīng)用程序開發(fā)人員所讀過的一些滑稽的注釋。請記住，我在應(yīng)用程序開發(fā)上有著20年以上的編譯經(jīng)驗(yàn)——反映了例外，而不是規(guī)則。

編碼快樂！

譯文鏈接：http://www.codeceo.com/article/8-useless-code-commenting.html
英文原文：Code Commenting Patterns
翻譯作者：碼農(nóng)網(wǎng) – 小峰