代碼要不要寫註釋？

近年來有一種思潮，認爲代碼不須要註釋——代碼即註釋。這種思潮是有必定道理的，但不少人難以正確領會。

這一思潮的興起是因爲以往提倡多寫註釋，不少人沒能正確領會「多寫註釋」的意義，寫了一大堆多餘甚至有錯誤的註釋：

• 當註釋內容與代碼內容重複時，註釋就是多餘的：
  // update status
  updateStatus();
• 當註釋內容與代碼的實際做用不一致時，註釋就是錯誤的：
  // copy node to new position
  moveNode(node, position);

然而，若是代碼就能代替註釋，那Java標準庫源碼爲何要寫那麼多註釋？

代碼即註釋的前提是：代碼能表達充足而明確的語義，從而能替代註釋的做用。這麼作能反過來促進編寫更加語義化的代碼，改進代碼質量，可是這須要代碼的做者和審查者有足夠好的品味。品味從哪來？多學習，多思考。不假思索地堆砌代碼老是有害的。

新手在懂得很少的狀況下，難以把握合適的度——註釋是多寫一點好仍是少寫一點好？多寫不必定對，可是多思考一些老是沒錯的。新手要先學會寫註釋，而後才進一步去學減小沒必要要的註釋，不要一上來就用極簡風格，一行註釋都沒有，以至程序的意圖和邏輯使人費解。

關於如何作好「代碼即註釋」，可參考《代碼整潔之道》，有一個原則是類名、函數名和方法名要清晰表達「這是用來作什麼的」而不是「這是如何實現的」，例如save()優於saveToDisk()。關於如何寫好註釋，可參考《代碼大全》。

對於一個缺乏註釋的Java程序，能夠分幾個級別來逐漸增長註釋：

1. 類級Javadoc，說明這個類的職責和做用，使用者要注意什麼事項
2. 方法級和字段級Javadoc，說明這個方法或字段的用法和做用，使用者要注意什麼事項
3. 重要代碼行的註釋，說明這段代碼的「目的」或「爲何寫成這樣」

經過這一過程，代碼會變得更加易於理解。

總結成一句話：不必定要寫註釋，但必定要思考這個問題；若是不肯定，那就先寫上。