几种代码注释方式

    注释作为代码的补充，它来说明代码未说到的东西，有自己独立的价值。注释相比于其他文档，离代码最近，也就最容易被看代码的人关注，最容易被写代码的人去更新，自然的有更大的价值。我们知道衡量一个文档的价值，一个重要因素就是被人参阅的频率。要提高这个频率，就要它很方便的被人拿到，打开和阅读。注释在这方面无疑是最有优势的。

 

    我们要避免那些“假注释”。没有附加值的注释都是“假注释”，比如简单的复述代码的功能，而这些功能都可以从类的名字，方法或者变量的名字中轻易得到的。有些工具检查你的代码，强制你给所有的方法，参数，返回值，变量加注释，我认为这是不必要的。虽说严格照规定做没什么坏处，但它要占用你的时间，某些情况下占用了你的“黄金时间”，而在这些有限的时间里你本来可以产出更有价值的东西。

 

下面我列举几种注释方式：

 

1. 为什么。

 

    告诉人们你为什么要这样做。适合于一些让人迷惑的状况，例如你没有用常用的招数，用了一些“歪招”。

 

2. 怎么做。

 

    告诉人们你是怎么实现目标的。适合于一些需求清晰的情况。比如你是怎么去实现“分页”功能的。

 

3. 举例说明。

 

    这个我觉得最直观，对阅读代码的人最友好。适合于输入输出数据简单，关系明了的情况，比如：

 

    /**
     * Convert zone name to internal format.
     * samples:
     * 12.34.56.78 > 56.34.12.in-addr.arpa%
     * 12.34.56.78. > 56.34.12.in-addr.arpa%
     * 12.34.56 > 56.34.12.in-addr.arpa%
     * 12.34.56. > 56.34.12.in-addr.arpa%
     * sina.com > %sina.com %
     * sina.*.cn > sina.%.cn%
     * sina.* > sina.%
     * 56.*.12.in-addr.arpa > 56.%.12.in-addr.arpa%
     *
     */  

 

4. 参考资料。

 

     把参考资料的链接，或者位置写出来，让阅读代码的人可以去进一步了解。比如：

 

    /**
     * We have some violations between old system data and new system data, like
     * abbreviation value and full value, so we need to do some convert action. Please
     * refer to xxx.
     */

 

5. 维护建议。

 

    这个很有价值，也会让后面维护的人很感激。

 

    /**
     * Here is the only place to change the city codes and rdc codes.
     * The format of each line is
     *   [City Name]|[City Value]|[RDC Name]|[RDC Value]
     * 
     *  Please put the same rdc value in one bunch,
     *   e.g.
     *     'Lafayette|lf|Baton Rouge|br',
     *     'Baton Rouge|br|Baton Rouge|br',
     */

 

6. 开发故事。

 

    讲一下你开发的过程，决策的过程，以及任何有价值的信息。比如：

 

     /**
      * The old implementation have so many repeated code and redundant pages, we  have removed

      * all those repeated things and deleted more than 20 pages. It's a big improvement even there

      * are some ugly javascript code here, we should use JSON to encapsulate the data and move all

      * javascript to menus.jsp page, this is next step.
      */

 

    怎么把文档和注释有机的结合在一起，优势互补，这是一个可以深入讨论的命题。比如可以参照REST的理念，把文档，代码和注释资源化，用一个工具把这些东西自动编译整理为对人友好的开发文档，项目文档等。