Clean Code (1) 註解

「無瑕的程式碼」的圖片搜尋結果




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

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

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

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

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

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

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

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

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

Previous
Next Post »