什麼時候應該避免註釋程式碼？

本文由碼農網 – 小峰原創翻譯，轉載請看清文末的轉載要求，歡迎參與我們的付費投稿計劃！

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

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

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

不要註釋壞程式碼——重寫吧。——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()) {

}

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

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

結論

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

我想說的是，你不應該為你的壞程式碼註釋。請記住，“真理只存在於程式碼中”。