摘要——注釋簡單代碼會干擾對重要注釋的理解。程序開發(fā)者最好能用最精要的注釋來解釋重點(diǎn)代碼。
舉個例子，你打開一個電箱，里面有幾百根電線，蒙了吧。再一看，每根電線上面都有一個整潔的小標(biāo)簽。真是謝天謝地啊!但是，當(dāng)你一個個去翻看標(biāo)簽的時候，見鬼的，幾乎所有的標(biāo)簽都是空白的!
然后，在你花了整整一個小時去瀏覽每一個小標(biāo)簽之后，終于給你找到12條有用的信息，真心喜大普奔!當(dāng)然，希望在你頭腦一片混亂的時候得出的結(jié)果仍然是正確的，沒有遺漏，呵呵呵。
當(dāng)我需要研究代碼的時候看到到處都是垃圾注釋，唉，我的感覺就和上面在那么多標(biāo)簽里面找有用的一樣。見鬼的，想從一大堆垃圾注釋里確定哪個有用簡直就像大海撈針!
說一個常用的開源項目，里面都是這些垃圾注釋：
/**
* __construct function.
*
* @access public
* @return void
*/
public function __construct() {
…
}
再來一個：
/**
* Constructor
*/
public function __construct() {
…
}
還有一個
// Convert float to string
$value = float_to_string( $value );
這些注釋就跟電箱里的空白標(biāo)簽一樣，明晃晃的擺在那里，增加干擾還降低注釋的可用性?？吹竭@樣的注釋，怪不得那些可憐的開發(fā)人員要廢寢忘食了。
我敢肯定，那個把空白標(biāo)簽貼在每根電線上的電工自認(rèn)為這是一個特棒的主意，他幫助了那些在他后面來的人：他們有什么想寫的，只要在這些已經(jīng)貼好的標(biāo)簽上面寫就可以了。當(dāng)然也有可能他本來打算自己填好所有標(biāo)簽。撇開他的好意不說，這樣做的結(jié)果真心是糟透了，還不如只貼那有用的12張呢!
在編程的時候，開發(fā)人員經(jīng)常被告知要注釋，但是他們中很少有人知道怎樣注釋才好。所以開發(fā)人員注釋代碼的時候，并不是因為有必要，而是因為他們覺得這是義務(wù)。開發(fā)人員認(rèn)為如果在代碼中多多注釋，能表現(xiàn)他們工作能力。
見鬼的，這也不知道是哪門子的理論。我最厭煩每隔幾行代碼就有注釋，而實際上卻屁用沒有。注釋的作用絕對不是為了純粹炫耀我們是“不明覺厲”的程序員，而是為了重點(diǎn)記錄我們搞這些代碼的原因。這樣一來，那些垃圾注釋就能滾蛋了。看下面的例子:
// 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();
說說我的做法吧，當(dāng)我考慮是否要寫注釋的時候，我就問自己：如果以后回過頭來看這些代碼，我能不能一下子明白當(dāng)初為什么要這樣寫?如果以后我會非常感謝這些注釋，那么想也不用想，果斷寫上注釋。否則，就讓那些垃圾注釋見鬼去吧。
下載文檔
