3.注釋(代碼的整潔之道)

---

目錄

注釋不能美化糟糕的代碼

用代碼來闡述

好注釋

壞注釋

注：代碼的整潔之道PDF： https://pan.baidu.com/s/16PLDWPiusGjcUfW_jgOm5w 密碼: s708

---

1. 注釋不能美化糟糕的代碼

什么也不會比亂七八糟的注釋更有本事搞亂一個模塊，什么也不會比陳舊、提供錯誤信息的注釋更有破壞性。

注釋的恰當用法是你不我們在用代碼表達意圖時遭遇的失敗。

如果你發現自己需要寫注釋，再想想看是否有辦法翻盤，用代碼來表達。

注釋會撒謊，存在的時間越久，就離其所描述的代碼越遠，越來越變得全然錯誤。原因很簡單，程序員不能堅持維護注釋。

代碼在變動，在演變，但注釋卻不能隨之變動。

真實只在一處地方有：代碼。只有代碼能忠實地告訴你它該做的事情。所以，盡管有時需要注釋，也該多花心思盡量減少注釋量。

---

2. 用代碼來闡述

示例一

示例二

你更愿意看到哪個示例？

只要想上幾秒鐘，就能用代碼解釋你大部分的意圖。很多時候，簡單到只需要創建一個描述與注釋所言同一事物的函數即可。

---

3. 好注釋

有些注釋是必須的，也是有利的。不過要記住，唯一真正好的注釋是你想辦法不去寫注釋。

1. 法律信息

公司代碼規范要求編寫與法律有關的注釋，例如，版權及著作權聲明就是必須和有理由在每個源文件開頭注釋防止的內容。

2. 提供信息的注釋

有時注釋提供基本信息也有用處，例如，以下注釋解釋了某個抽象方法的返回值：

這類注釋有時很管用，但更好的方式是盡量利用函數名稱傳遞信息。比如，在本例中，只要把函數重新命名為responderBeingTested，注釋就是多余的了。

3. 對意圖的解釋

有時，注釋不僅提供了有關實現的有用信息，而且還提供了某個決定后面的意圖。

4. 闡釋

有時，注釋把某些晦澀難明的參數或返回值的意義翻譯為某種可讀形式，也會有用的。

通常，更好的方法是盡量讓參數或返回值自身就足夠清楚。但如果參數或返回值是某個標準庫的一部分，或是你不能修改的代碼，幫助闡釋其含義的代碼就會有用。

5. 警示

有時，用于警告其他程序員會出現某種后果的注釋也是有用的。

6. TODO注釋

TODO注釋解釋了為什么該函數的實現部分無所作為，將來應該是怎樣。

TODO是一個程序認為該做，但由于某些原因目前還沒做的工作。

6. 放大

注釋可以用來放大某種看來不合理之物的重要性。

---

4. 壞注釋

大多數注釋都屬于此類。通常，壞注釋都是糟糕的代碼的支撐或借口，或者對錯誤決策的修正，基本上等于程序員自說自話。

1. 喃喃自語

如果只是因為你覺得應該或者因為過程需要注釋，那就是無謂之舉。如果你決定寫注釋，就要花必要的時間確保寫出最好的注釋。

2. 多余的注釋

下面代碼展示了簡單函數，其頭部位置的注釋全屬多余，讀這段注釋花的時間沒準比代碼花的時間還要多。

3. 誤導性注釋

4. 循規式注釋

所謂每個函數都要有javadoc或每個變量都要有注釋的規矩全然是愚蠢可笑的。這類注釋只會搞亂代碼，有可能誤導讀者。

5. 日志式注釋

6. 廢話注釋

7. 可怕的廢話

8. 能用函數或變量時就別用注釋

代碼一

可改成以下沒有注釋的版本

作者應該重構代碼，而不是寫注釋。

9. 位置標記

程序員喜歡在源代碼標記某個特別位置。如

把特定函數放在這種標記欄下，多數時候實屬無理，理當刪除。

10. 括號后面的注釋

有時，程序員會在括號后面放置特殊的注釋，盡管對含義深度嵌套結構的長函數可能有意義，但只會給我們更愿意編寫的短小、封裝的函數帶來混亂。

如果你發現自己想標記右括號，其實應該做的是縮短函數。

11. 歸屬與署名

源代碼控制系統非常清楚誰在何時添加了什么，沒必要用那些小小的簽名搞臟代碼。

注釋在那放了一年又一年，越來越不準確，越來越和原作者沒關系。

12. 注釋掉的代碼

直接把代碼注釋掉是討厭的做法，別那么干！

13. HTML注釋

源代碼注釋中的HTML標記是一種厭物。

14. 非本地信息

假如你一定要注釋，請確保它描述了離它最近的代碼。別在本地注釋的上下文環境中給出系統級的信息。

15. 信息過多

別在注釋中添加有趣的歷史性話題或者無關的細節描述。

16. 不明顯的聯系

注釋及其描述的代碼之間的聯系應該顯而易見。

17. 函數頭

短函數不需要太多描述，為只做一件事的短函數選個好名字，通常比寫函數頭注釋要好。

18. 非公共代碼中的javadoc

19. 范例

總結

以上是生活随笔為你收集整理的3.注释(代码的整洁之道)的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。