英文原文：When Should You Avoid Commenting Your Code?

　　看到標題，我知道你可能會想：“我為什么要避免代碼注釋，這難道不是一件好事嗎？”。是的，寫注釋在大多數情況下是有用的。但是，請注意，我說的是“在大多數情況下”，因為有一些情況下，你不應該寫注釋。

　　還不相信？那讓我告訴你：寫注釋有時會壞事！會導致壞代碼！

　　請允許我用一句名言來開始我的論證：

不要注釋壞代碼——重寫吧。——Brian W. Kernighan and P. J. Plaugher

　　這句話給我流下了非常深刻的印象。仔細想一想，有多少次你注釋你的代碼，只是因為擔心自己將來再回過頭來閱讀的時候可能會不理解它的意思？至少都做過一次吧。坦率地說，我有很多次是因為這個原因才注釋的，尤其是在那些我還是重構和編寫干凈代碼的新手的日子里。

　　那么，為什么這樣的注釋反而不好呢？簡而言之是因為，我們會因為有注釋而放任編寫壞的代碼！正如你所看到的，注釋有時候反而激勵了我們去寫一些不整潔的代碼。

　　另一個原因是因為注釋會誤導我們。有多少次你已經改變了代碼，卻忘了改旁邊的注釋？別否認，這種事時常發生。這就是為什么你經常聽到這樣一句話，“真理只存在于代碼中”。

　　那么，什么時候你不應該寫注釋呢？

　　有一個經驗法則就是，無論何時你發現自己要使用注釋來解釋這段代碼是用來干什么的時候，那么基本上就是你的代碼需要重構以變得更整潔的時候。

　　典型的解決方案

　　現在你知道為什么有時候反而要避免寫注釋了，那么有什么解決辦法嗎。事實上，目前還沒有一個有效的解決方案，但是你可以清潔你的代碼，這樣你（以及其他人）就可以在沒有注釋的情況下也能理解它了。

　　為了用可讀的代碼替換掉注釋，通常我們的典型解決方法是使用提取方法重構（Extract Method refactoring）。這種重構方式是我最喜歡的。對此我也寫過一篇博客，里面有完整的例子：《Break Your Method Into Smaller Ones》。

　　下面讓我們看一個簡單說明如何提高你的代碼，從而解放注釋的例子。

<?php
// Check to see if the customer can get free product
if ($customer->isPremium () and $customer->numberOfPurchases > 8) {
}
// OR
if ($customer->canGetFreeProduct ()) {
}

　　我希望你能注意到這兩個條件語句之間的差異。哪一個更整潔？很明顯第二個更整潔，更好。這是因為，首先，可以刪除注釋，因為我們看代碼就明白了意思。其次，也是最重要的一點是，我們提取了檢查客戶是否值得獲得免費產品的邏輯到它的方法中，這是一件好事，特別是當你想要在應用程序中再次使用它的話。

　　對于更詳細的例子，我推薦你閱讀我以前發表過的文章。

　　結論

　　請允許我用一個免責說明來結束這篇文章。我不反對注釋。注釋在大多數情況下是非常有用的，尤其是在開源項目中。

　　我想說的是，你不應該為你的壞代碼注釋。請記住，“真理只存在于代碼中”。

　　-

　　譯文鏈接：http://www.codeceo.com/article/when-avoid-comment-code.html

　　翻譯作者：碼農網 – 小峰