關於指令碼中注釋的五點建議

指令碼  

　　當你學習某代碼技術已經基本入門以後，自然會注意到提高代碼品質的重要性，而書寫注釋則是提高代碼品質的第一關——可能也是最容易的一關。以下是我總結的關於書寫注釋的一些建議！

　　一、切勿為了注釋而注釋！

　　為代碼添加註釋的最主要目的是提高代碼可讀性，但這裡面還有一個心態問題：如果你認為，寫了注釋，就可以提高代碼品質，就可以證明實力，那就錯了，事情並沒有那麼簡單。

　　相信一定有人在寫注釋的時候，沒有把握正確的心態，這就導致寫出來的注釋往往不合時宜。什麼是不合時宜的注釋？我就寫過這樣的注釋：

　　……
　　'開啟記錄集，記錄Orders表所有資料
　　objRS.Open "SELECT * FROM Orders",objConn,1,1
　　……
　　objRS.Close '關閉記錄集
　　Set objRS=Nothing '釋放記錄集對象
　　……

　　明白了吧？這就是不合時宜的注釋的情形之一：形式化的注釋，往往會成為代碼的累贅，甚至無法突出真正需要注釋的地方，降低了代碼的可讀性。

　　這都是心態沒有把握好的原因。如果能正確把握心態，就會把心思放到提高代碼可讀性上，而不是放到寫注釋上了！寫注釋只是提高代碼可讀性的手段之一，而且寫注釋也是要講技巧和效率的。下面將對此進行討論。

　　二、廢話連篇的注釋不是好注釋！

　　在我看來，優秀的命名規範和代碼格式往往比注釋更能提高代碼可讀性。命名規範可以說明代碼元素的作用，而代碼格式則能使編程思路更清晰——不過很遺憾，它們無論如何都跳不出代碼的圈圈，對代碼的描述能力並不強，所以我們還是要依靠注釋。

　　因此，我們應該先在命名規範和代碼格式兩個方面嚴格要求自己，然後再以注釋為輔助來描述代碼。——請不要懷疑，你讀代碼的時候是先看代碼還是先看注釋？一般的情況是，代碼能明確說明的問題往往就不需要看注釋了，比如上面第一點裡寫出的那些垃圾注釋，沒人會把它們當回事的（但被當作入門教程中的樣本還不錯）。當然，也有例外，以注釋為代碼主要描述手段的情況在第三點討論。

　　什麼樣的注釋才是合時宜的呢？在適當的地方，以適當的篇幅寫出來的注釋就是合時宜的。我不能給你更具體的答案，但方向已經指明了，你需要做的就是思考、參考、再思考……總之，讓注釋也和代碼一樣簡單、優雅而又有效就是目標，這樣的代碼才能達到提高代碼可讀性的效果！

　　僅僅是合時宜還不夠，如果注釋含糊不清，仍然不是好注釋！所以，讓注釋更準確地描述代碼同樣重要，特別是對函數/過程、技巧性質的程式碼片段等。以昨天那篇文章（你抄近道了嗎？——源自兩個VBS過程的感慨）中提到的兩個過程之一——GetRandom——為例，我為其作用的描述是：返回從源數組中隨機抽取指定數目的位置不重複元素組成的新數組。如果讓你描述它的作用，你會如何描述？請不要誤會，我可不是在自賣自誇，我只是取了一個離自己最近的例子而已。

　　總之，好的注釋，要合時宜，還要準確有效！否則不如不寫。

　　三、外部文檔往往比內部注釋更有效！

　　你也許會奇怪，我上面強調了函數/過程和技巧性質的程式碼片段的注釋要準確，為什麼我沒有提到對類的注釋呢？個人以為，如果程式廣泛採用了面向（或者基於）對象的設計方法，對類的注釋應該從長計議。情況之一是，如果類需要封裝，那注釋也只在設計時有效，對提高代碼可讀性的意義不大；情況之二是，類的設計和使用應該宏觀把握，而代碼中的注釋往往是微觀的描述，很難達到宏觀描述的效果——比如許多用圖才好描述的類別關係，注釋的效果就不好。

　　這個時候，我們就需要有外部文檔了！不要問我什麼是外部文檔，如何寫外部文檔。總之，一切為提高代碼可讀性服務，做你能做的一切。

　　還有一個問題要說，到底該在什麼時候寫注釋和文檔呢？有些人是先把代碼寫好，再趁著自己沒有淡忘之前把注釋補上；有些人先寫好設計草案，然後再開始寫代碼……其實沒有對錯，達到目的就好。——注意，理性統籌的正規項目工程開發不在討論範圍內，這種開發要考慮的因素太多了，不能那麼隨意的。

　　四、盡量避免用戶端注釋！

　　用戶端注釋的唯一缺點應該是增加I/O壓力吧？大家可以算一算，如果為HTML和用戶端指令碼添加註釋，主觀估計將為每頁增加1K位元組，現在剩下的就是估計頁訪問量了……

　　為什麼要為用戶端指令碼和HTML添加註釋呢？特別是為HTML添加註釋更是難以理解——也可能是我沒見識吧，呵呵。標準化的B/S用戶端設計講究結構、呈現、行為的分離，我想這是對用戶端代碼最好的注釋吧？

　　五、常審視和改善以前代碼中的注釋！

　　寫注釋很大程度上也是為了防止自己以後讀到這些代碼的時候也不明其意，所以，如果能經常審視和改善以前代碼中的注釋……呵呵，還是不多說了吧，相信大家用膝蓋想也能明白其中的好處。——怎麼感覺我的文章都是虎頭蛇尾？

　　最後，祝所有專情的人好運！