注释作为代码的补充,它来说明代码未说到的东西,有自己独立的价值。注释相比于其他文档,离代码最近,也就最容易被看代码的人关注,最容易被写代码的人去更新,自然的有更大的价值。我们知道衡量一个文档的价值,一个重要因素就是被人参阅的频率。要提高这个频率,就要它很方便的被人拿到,打开和阅读。注释在这方面无疑是最有优势的。
我们要避免那些“假注释”。没有附加值的注释都是“假注释”,比如简单的复述代码的功能,而这些功能都可以从类的名字,方法或者变量的名字中轻易得到的。有些工具检查你的代码,强制你给所有的方法,参数,返回值,变量加注释,我认为这是不必要的。虽说严格照规定做没什么坏处,但它要占用你的时间,某些情况下占用了你的“黄金时间”,而在这些有限的时间里你本来可以产出更有价值的东西。
下面我列举几种注释方式:
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的理念,把文档,代码和注释资源化,用一个工具把这些东西自动编译整理为对人友好的开发文档,项目文档等。