別給糟糕的代碼加注釋——重寫吧。
注釋是用來彌補我們在用代碼表達意圖時遭遇的失敗，若代碼足夠有表達力，就不需要注釋。注釋有時會撒謊。注釋存在的時間越久就離其所描述的代碼越遠，原因是程序員不能堅持維護注釋。不準確的注釋要比沒注釋糟糕的多。只有代碼能真實的告訴你他做的事。我們在寫注釋時需要遵循以下原則。

1.注釋不能美化糟糕的代碼。寫注釋的常見動機之一是糟糕代碼的存在，帶有少量注釋的整潔而有表達力的代碼，要比帶有大量注釋的零碎而復雜的代碼好的多。與其花時間編寫注釋，不如花時間清潔那堆糟糕的代碼。

2.用代碼來闡述。有些代碼本身不足以解釋其行為，程序員認為代碼寫少了，這顯然是錯誤的觀點。很多時候簡單到只需要創建一個描述與注釋所言同一事物的函數即可。

3.有些信息必須用注釋來表達。1)法律信息，比如版權及著作權聲明。但不需要把所有的條款都放在注釋中。2)對意圖的解釋。注釋不僅提供了有關實現的有用信息，而且還提供了某個決定后面的意圖。3)晦澀的參數或返回值。注釋把某些晦澀難懂的參數或返回值的意義翻譯為某種可讀形式。4）警示。用于警告其他程序員修改這段代碼會出現某種后果。5）TODO注釋。程序員認為應該做，但由于某些原因目前還沒做。他可能要求他人注意某個問題。6)公共API中的javadoc。如果你在編寫公共api，就該為他編寫良好的javadoc。

4.不應該添加你認為，你覺得或因為過程需要的多余，無用注釋。

5.不要添加誤導性注釋。

6.不要添加循規式注釋。比如要求每個函數都要有javadoc或每個變量都要有注釋的規矩顯示是錯誤的。

7.不要有日志式注釋。有人在編寫代碼時，在模塊開始處添加一堆注釋，這種注釋就是想是一種記錄每次修改的日志。

8.少用注釋當做位置標記欄。

9.少在括號后面添加注釋。這對于含有深度嵌套結構的長函數可能有意義，但也說明了你的函數不夠短小。

10.不要寫歸屬和署名。這種注釋可能有助于他人了解當時和誰談論了代碼，不過事實卻是注釋在哪放了一年又一年，越來越不準確，越來越和作者沒關系，源代碼控制系統會為你很好的做這件事。

11.及時清理被注釋掉的代碼。其他人不敢刪除注釋掉的代碼，他們會想代碼自然，放在那一定有其原因，不能刪除。其實，注釋掉的代碼隨著時間的推移會越來越多。該刪除的代碼就刪除，他們丟不了，相信現在的版本控制系統。

12.別在本地注釋體現出系統級信息，比如端口號。這個信息也許并未描述該函數，而是在描述系統中遠在其他地方的其他函數。

13.別在注釋中添加有趣的歷史話題和無關的描述。

總結

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

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