如何在JavaScript中谨慎使用代码注释

前言

最令程序员头痛的事情莫过于阅读别人的代码，但其实时间一久阅读自己的代码也会很痛苦。 问题不是出在『自己或别人』，而是在代码本身。

必要的注释可以阐明实现细节和设计意图，以此节约自己和别人的时间。 然而很多时候注释起的作用却适得其反，比如自动生成的过多的注释分散阅读者的注意力， 而过期的失效的注释更是误导阅读者。

自动生成的注释

代码注释的泛滥想必是从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.*/

文件头注释清晰地列出了文件的作者、功能描述等信息，看起来很有用。 不过这样的文件头存在的问题在于其维护性：