摘要——注釋簡(jiǎn)單代碼會(huì)干擾對(duì)重要注釋的理解。程序開發(fā)者最好能用最精要的注釋來(lái)解釋重點(diǎn)代碼。

舉個(gè)例子，你打開一個(gè)電箱，里面有幾百根電線，蒙了吧。再一看，每根電線上面都有一個(gè)整潔的小標(biāo)簽。真是謝天謝地啊!但是，當(dāng)你一個(gè)個(gè)去翻看標(biāo)簽的時(shí)候，見(jiàn)鬼的，幾乎所有的標(biāo)簽都是空白的!

然后，在你花了整整一個(gè)小時(shí)去瀏覽每一個(gè)小標(biāo)簽之后，終于給你找到12條有用的信息，真心喜大普奔!當(dāng)然，希望在你頭腦一片混亂的時(shí)候得出的結(jié)果仍然是正確的，沒(méi)有遺漏，呵呵呵。

當(dāng)我需要研究代碼的時(shí)候看到到處都是垃圾注釋，唉，我的感覺(jué)就和上面在那么多標(biāo)簽里面找有用的一樣。見(jiàn)鬼的，想從一大堆垃圾注釋里確定哪個(gè)有用簡(jiǎn)直就像大海撈針!

說(shuō)一個(gè)常用的開源項(xiàng)目，里面都是這些垃圾注釋：

/**

* __construct function.

*

* @access public

* @return void

*/

public function __construct() {

…

}

再來(lái)一個(gè)：

/**

* Constructor

*/

public function __construct() {

…

}

還有一個(gè)

// Convert float to string

$value = float_to_string( $value );

這些注釋就跟電箱里的空白標(biāo)簽一樣，明晃晃的擺在那里，增加干擾還降低注釋的可用性。看到這樣的注釋，怪不得那些可憐的開發(fā)人員要廢寢忘食了。

我敢肯定，那個(gè)把空白標(biāo)簽貼在每根電線上的電工自認(rèn)為這是一個(gè)特棒的主意，他幫助了那些在他后面來(lái)的人：他們有什么想寫的，只要在這些已經(jīng)貼好的標(biāo)簽上面寫就可以了。當(dāng)然也有可能他本來(lái)打算自己填好所有標(biāo)簽。撇開他的好意不說(shuō)，這樣做的結(jié)果真心是糟透了，還不如只貼那有用的12張呢!

在編程的時(shí)候，開發(fā)人員經(jīng)常被告知要注釋，但是他們中很少有人知道怎樣注釋才好。所以開發(fā)人員注釋代碼的時(shí)候，并不是因?yàn)橛斜匾且驗(yàn)樗麄冇X(jué)得這是義務(wù)。開發(fā)人員認(rèn)為如果在代碼中多多注釋，能表現(xiàn)他們工作能力。

見(jiàn)鬼的，這也不知道是哪門子的理論。我最厭煩每隔幾行代碼就有注釋，而實(shí)際上卻屁用沒(méi)有。注釋的作用絕對(duì)不是為了純粹炫耀我們是“不明覺(jué)厲”的程序員，而是為了重點(diǎn)記錄我們搞這些代碼的原因。這樣一來(lái)，那些垃圾注釋就能滾蛋了。看下面的例子:

// We need to account for product price changes,

// so we get the price of the product when each order occurred

$order_prices = $this->get_order_prices();

說(shuō)說(shuō)我的做法吧，當(dāng)我考慮是否要寫注釋的時(shí)候，我就問(wèn)自己：如果以后回過(guò)頭來(lái)看這些代碼，我能不能一下子明白當(dāng)初為什么要這樣寫?如果以后我會(huì)非常感謝這些注釋，那么想也不用想，果斷寫上注釋。否則，就讓那些垃圾注釋見(jiàn)鬼去吧。