前言

最令程序員頭痛的事情莫過于閱讀別人的代碼，但其實時間一久閱讀自己的代碼也會很痛苦。 問題不是出在『自己或別人』，而是在代碼本身。

必要的注釋可以闡明實現細節和設計意圖，以此節約自己和別人的時間。 然而很多時候注釋起的作用卻適得其反，比如自動生成的過多的注釋分散閱讀者的注意力， 而過期的失效的注釋更是誤導閱讀者。

自動生成的注釋

代碼注釋的泛濫想必是從Eclipse，Visual Studio等IDE開始的。 這些IDE提供了很多快捷功能，生成類/接口的骨架，具有Getter/Setter的屬性等等。 如果用過IDE，下面的代碼你一定不會陌生：

/*** @param args*/public static void main(String[] args) {// TODO Auto-generated method stub}

上述6行代碼中的4行注釋包含的信息量是0，既沒有闡釋參數args是何物，也沒有說明main的用途。 然而大量的項目中都充斥著這樣的自動生成注釋。

『建議』：如果有參數或機制需要說明，請補充這些信息。否則請刪除自動生成注釋。 當然，用于生成文檔的注釋除外。

過多的注釋

總會有人不厭其煩地編寫長篇累牘的注釋，或無微不至，或語焉不詳，或晦澀難懂，或文采飛揚。 總之沒有幫助我更快閱讀代碼的注釋都是失敗的注釋。

為了說明問題，Harttle克隆了4.x Linux Kernel源碼， 來大致分析一下其注釋行數。 我們知道內核代碼95%以上是C語言，所以統計.c文件就足夠說明問題了。

➜ linux git:(master) git clone git@github.com:torvalds/linux.git --depth=1➜ linux git:(master) find . -name "*.c" -o -name "*.h" -exec grep -E '^/s*((/*)|(/[/*]))' {} /; | wc -l724804➜ linux git:(master) find . -name "*.c" -o -name "*.h" -exec cat {} /; | wc -l4018961➜ linux git:(master) node> 724804/(4018961-724804)0.22002715717556875

內核倉庫中的代碼大概是402萬行（未移除空行），其中注釋72萬行，占比22%。 Linux內核使用低級的C語言編寫，涉及到復雜的CPU調度、內存管理，驅動程序。 因此注釋會偏多一些，一般的項目注釋應小于這個數值。

『建議』：如果你的代碼中注釋超過了20%，那么顯然你過度注釋了。

文件頭注釋

很多編輯器/IDE都會生成默認的文件頭，例如：

/*** @file /tmp/xxx.js* @author harttle(yangjvn@126.com)* @date 2016-08-30 22:33* @description A XXX Implementation for XXX.*/

文件頭注釋清晰地列出了文件的作者、功能描述等信息，看起來很有用。 不過這樣的文件頭存在的問題在于其維護性：