别給糟糕的代碼加注釋 -- 重新寫吧。 Brian W.Kernighan 與 P.J.Plaugher

有一個關于程序員的段子，說所有的程序員都讨厭兩件事，一是别人不寫注釋，二是自己寫注釋。關于寫注釋，一直有人争論不休，有的人認為寫代碼必須要寫注釋，而又的人認為代碼就是注釋，何必再寫一遍？那麼今天我們就聊一聊代碼中的注釋。

寫注釋

為什麼要寫注釋？注釋就是彌補我們在寫代碼的過程中，代碼表達的含義不清或者容易造成混亂的時候才加上的，或者是對于代碼可能存在的風險加以說明，或者警示函數調用者使用規範等。

不寫注釋

什麼情況下不寫注釋？先舉一個簡單的例子：

很明顯這種就是多餘的注釋，這種注釋完全就是多餘的，除了增加閱讀人的難度，毫無任何意義。再比如：

這段代碼看起來貌似沒什麼問題，注釋寫的也算明确，檢查員工是否有資格獲得全額福利，檢查條件是标志 flags 為 HOURLY_FLAG 并且年齡大于 65 歲。但是實際上，上面的注釋是完全沒有必要寫的，我們看下面修改後的代碼：

我們直接把這個判斷條件封裝成一個方法，這個方法名實際上就“等同于”注釋了，所以說上面的注釋完全可以不用加。

---

好注釋

什麼是好注釋？有些地方是一定要寫注釋的，這些地方的注釋一定要盡可能的詳細，并且無歧義。比如在合作開發的時候，寫的一些 API ,這些 API 的函數的參數、返回值、以及函數的作用。例如 CSharp 中 System.Math.Max 函數：

這些注釋是非常好的注釋，并且非常的詳細。如果你寫的代碼将來也是要封裝成 API 的，建議也要寫的非常規範，以方便調用者使用。有返回值的，一定要詳細解釋好返回值的含義，比如：

判斷一個字節是否是十進制數字。我們注意看返回值的注釋，詳細寫道， true 表示是一個十進制數字，否則返回 false。工作中我見到過很多開發者寫的類似返回 bool 值的方法的注釋，都類似“是否是一個十進制數字”這樣，這樣就不是一個好注釋，那麼到底是 true 代表“是”還是 false 代表“是”呢？是不是容易混淆？

還有，再比如有些方法内的函數調用必須要有嚴格的調用順序，這時候注釋也是一定要加的，比如：

因為在後續功能擴展的時候，很有可能在其内部添加一些其他的函數調用，并且這個功能并不一定是當初開發這個函數的人繼續擴展添加，如果調用順序發生錯誤，很可能會出現很多麻煩。

壞注釋

有一段非常經典的代碼，求平方根倒數:

這段代碼的經典之處除了以非常高效的速度算出來平方根的倒數，還因為其中的一句 wtf 的注釋，很明顯這個 0x5f3759df Magic Number 沒人知道是幹什麼的。（有人通過數學公式推導出了這個魔法數字的由來，鍊接）。很明顯這裡的注釋明顯不足，至少這裡要注釋上推導過程或者是利用什麼數學公式推算的，因為我們并不能保證所有的程序員都有這樣的數學功底。

還有一些注釋，就是有些開發者喜歡在注釋裡添加姓名和日期，例如：

加這種注釋一般都是覺得方便以後他人遇到問題知道該和誰讨論，但是事實上，注釋放了一年又一年，下一個人修改代碼的時候很可能沒有加日期和姓名，将來有問題的時候找到第一個加注釋的人，他也看不懂為什麼改成了這樣。為什麼沒必要加這類注釋？因為我們都會有代碼版本控制的軟件，這是最直接最方便找到修改者的方法，而不是看上面這段不一定準确的注釋來找這段代碼的開發者。

說到這裡，還要順便說下一種壞注釋，那就是錯誤的注釋。誤導性的注釋比沒注釋更可怕。當我們修改一個函數的時候，如果函數的最初的注釋和最新的實現不匹配，一定記得要修改一下注釋，哪怕是删掉注釋，也不要留着誤導性的注釋。

---

總的來說，有些注釋是必須要有的，而且于己于他都是有利的。不過函數内部的一些注釋，最好的注釋就是想辦法不去寫注釋，讓自己的代碼成為最好的注釋，一些函數的命名，最好讓看代碼的人不必進到函數實體内看具體實現就知道大概在幹什麼，這是最好的；變量命名一定不要有歧義，哪怕長一點，盡量不要用縮寫，保證代碼的可讀性，這樣你就可以和别人吹牛了：我寫的代碼還用加注釋？

不過說到底，注釋就是輔助其他人來閱讀代碼用的，輔助提升代碼的可讀性。提高代碼的可讀性，是一條漫長的路，初學者可以看一下一些 IT 公司的代碼規範，平時也要嚴格要求自己，讓自己的代碼更加整潔清晰。

,

更多精彩资讯请关注tft每日頭條，我们将持续为您更新最新资讯!

查看全部