過年期間翻了這本書，可能是我有年紀了，看這種技術偏硬的書著實有些吃力了，一個過年下來還沒有看完。不過，這本書看了真的會讓你猛點頭。有些過去自己感覺不太對的地方，看了這本書有點豁然開朗的感覺。

比如說，以前看到程式裡頭有一些被註解的程式碼，總會覺得怪怪的。也曾經對成員宣導過不要留註解的程式碼在 source code control 上。但是這樣的程式碼在很多地方都看得到，包括我們使用的 open source 的原始碼當中都有不少。

過去的習慣在改掉程式碼前會先將原來的程式碼註解，一方面當作參考，另一方面也是怕改爆了，可以馬上復原。但我們比較少做的是，在確認修改完成後，並沒有清理戰場，把不必要的垃圾清除。那些被註解的程式碼久了就會變成垃圾。因為沒有人知道打開註解後會不會動，也不會知道該不該打開。

舉一個例子，假設一段程式碼有兩種實作方式，而現況是註解一種，打開另外一種。過了一年半載，如果維護的人換了，這就會變成無頭公案，沒有人知道這兩段怎麼來的，也不會知道接下來怎麼維護。

如果你的想法是，遇到這種狀況，再寫一個註解去說明這兩種實作的差異，那麼你很會就會遇到程式碼與註解同步的問題。比如說現在開啟的是第一個實作，但是某個罕見的場景失敗了，被回報 bug，這時候解 bug 的人看到有第二個實作，他的想法會是 "先修改註解，然後再交換兩種實作的註解狀態" 還是會 "直接先交換註解狀態，試試看，耶 OK 了，然後就把註解的事情忘得一乾二淨" 呢? 我猜後者的可能性居多吧。所以時間一久，維護換了幾手，整個程式碼就會變得很難相信。

另一個例子是過去在 visual source safe 年代，一個檔案的前面會有修改歷史紀錄，而且這些紀錄是系統在你每次 checkin 自動加上去的。所以當你打開檔案時，得先翻個四五頁才看得到真正的程式碼。過去我覺得這怪怪的，所以後來內部因為組織架構改變，程式碼分家後，我馬上就砍了這些註解。到現在我還有點心虛，這樣到底對不對。不過看了 Bob 大叔的話，我馬上就理解，砍掉是對的，保存歷史應該是系統的事，而不是放在檔案裡頭。

另外過去有一段時間，我很執著在自動產生文件這件事，所以找了 doxygen，也一度要求函式開頭要有一堆註解的說明。到後來這個動作也自然被淘汰了。原因無他，因為這種註解只有被創造時與事實相符，之後就變成誤導人的東西了。

最震撼的應該是程式內文內的註解，因為過去的訓練幾乎都在談，該利用註解來輔助你的讀者了解你的程式碼。不過 Bob 大叔很直接地說了：註解無法彌補糟糕的程式碼、用程式表達你的本意。這就是說，盡量不要用到註解，如果需要用註解才能說明，就表示你的程式碼需要被重構，直到他們能夠達意為止。

最後，你是不是看過程式碼有不少的 TODO? 你有沒有計算過這些 TODO 多久會消失? 我想，大部分的 TODO 都是恆久遠地，重來沒有被移除地。即使他們想傳達的東西後來已經沒有必要，或甚至已經被做出來了。但是因為註解的維護不那麼重要，所以通常不會被更新。這就證明了 Bob 大叔的觀點看來是有道理的，所以是不是該去清清程式碼裡頭無用的註解了呢?