Kevlin Henney

理論與實踐的差距#

理論與實踐之間的差距在實踐中比在理論中更大——這個觀察在註解這件事上尤其適用。理論上，為程式碼加註解聽起來很值得：為讀者提供細節、解釋正在發生的事情。還有什麼比這更有幫助的呢？然而在實踐中，註解往往變成一種災禍（blight）。

就像任何形式的寫作一樣，寫好註解是一種技巧。而這項技巧的很大一部分在於知道什麼時候不該寫。

有害的註解#

當程式碼格式不良時，編譯器、直譯器和其他工具肯定會提出異議。程式碼如果功能有誤，review、靜態分析、測試和日常的生產環境使用會揪出大多數 bug。但註解呢？在 The Elements of Programming Style 中，Kernighan 和 Plauger 指出：「一個值為零（或負數）的註解，如果它是錯誤的」。然而這類註解往往在程式碼庫中存活，以一種程式碼錯誤永遠做不到的方式持續存在。它們是持續的干擾和誤導來源，對程式設計師的思考造成微妙但持久的拖累。

毫無價值的註解#

哪些註解在技術上不算錯，但對程式碼毫無附加價值？這類註解是噪音（noise）：

• 鸚鵡式地重複程式碼已經表達的東西——用自然語言再說一遍並不會更真實或更實際
• 被註解掉的程式碼（commented-out code）——對讀者或執行環境都沒有用處，而且很快就會過時
• 與版本相關的註解——這些問題版本控制工具已經回答得更好了

噪音註解的危害#

程式碼庫中大量的噪音註解和錯誤註解，會鼓勵程式設計師忽略所有註解——要麼跳過它們，要麼主動採取措施隱藏它們（折疊、換色、寫腳本過濾等）。為了避免這種「狼來了」效應，具有真正價值的註解應該像對待程式碼一樣被對待：每個註解都應該為讀者增加一些價值，否則就是應該被移除或重寫的浪費。

什麼才算有價值#

註解應該說一些程式碼沒說也不能說的東西：

• 一個解釋程式碼「已經在做什麼」的註解，其實是在邀請你修改程式碼結構或編碼慣例，讓程式碼自己說話
• 與其為糟糕的方法名或類別名寫補償性的註解，不如重新命名它們
• 與其為長函式中的區段加註解，不如提取成小函式，用名稱表達原意圖

盡量透過程式碼表達一切。你能用程式碼表達的和你想要完整表達的之間的落差，才是有用註解的合理候選。註解程式碼不能說的東西，而不只是它沒說的東西。