Krilo 的筆記本

A Passing Comment --- 逝去的註解

Quality is more important than quantity. ---- 品質比數量更為重要。
先前 Mr. Goodliffe 所主張的 Self-documented Code，非常容易和這次所要介紹的主題有所混淆，在這裡我們所要釐清的是，Self-Documented Code 的形成，註解，並不是其主要的部份，也就是說，我們也不應該依賴眾多的註解來達到所謂的自我文件化的程式碼。

而對於註解 (comment) 的認知，作者寫道...
Comments are our lifelines, memory logs, and guides through code.
We should only be writing comments when they really add something.
我們對於註解的態度應該是：非必要，我們不加註，要加就要加的有價值。

以下有幾點值得我們注意...

1. Explain why, not how
在實際的經驗中，我們時常會看到一段註解像是...
// 設定參數 something
request.setAttribute(something,other);

這樣的註解其實它帶給我們的價值和意義來說，都沒有多大的效用，光看第二行的程式，就可以清楚地明暸其動作(或是 How)，重點在於會做這件事的一個動機。所以，在加註時，我們應該加註的是，WHY，而不是 How，這一類型的註解有點 over-documented 或是 duplicate code，應該要避免。記住，one source, do NOT duplicate code in a comment。

2. When you find yourself writing dense comments to explain your code, step back. Is there a bigger problem to solve?
當你發現你正在寫一大堆註解來解釋你的程式時，可以退一步來思考，是不是還有一個更大的問題沒有解決?
在這裡，作者提出這一個線索來指引我們，當程式連註解都要像寫一篇文章一樣來解釋時，我們是否已經把該問題解析清楚了，或許該是重新思考的時候了。

3. Comments should live in the present, not the past.
Don't describe things that have changed, or tell what something used to do.
註解應該反應現在程式的狀況，而不是過去的情形，我們不需要去敘述過去是如何去實作的。
開發時，大部份都會有所謂的 version management 的機制來管理先前的 code ，所以我們更不要花時間去寫或是講述之前的 code，這也是會犯了 duplicate code 的錯誤。我想這是本章節的重點，a passing comment ，逝去的註解，註解是形容現有 code 的狀態。

4. When you alter code, maintain any comments around it.
當你正修改程式碼時，別忘了要去維護相關的註解，這點是呼應上一點，我們應該要順便去維護註解，使其永保如新。

5. Choose a Low-Maintenance Style: beauty and maintenance balance.(選擇一個維護性低的形式: 美觀和維護的平衡)
這當然是成本的考量，不同形式的comment 或是 style 都有優缺點，而我們應該在這兩點找到一個平衡。而本書當然還有其他不錯的想法，等著大家去發掘吧!

參考文章。