原则:尽量用代码来解释自己
我们必须认识到,写注释从某种意义上来说是一种“失败”,是我们无法用代码来解释意图而必须借助于注释。因此在写注释前要慎重思考,看能否通过改善代码可读性来避免写注释。
规则1:注释应解释代码的意图,而不是描述代码怎么做的
规则2:保证注释与代码一致,避免产生误导
注释造成误导,危害性很大,还不如不写。很多误导的产生,并不是有意为之,而是在代码修改的同时没有修改对应的注释造成的。因此,如果写了注释就要保证注释与代码的一致性,避免产生误导。如果注释不再有用,必须删除。
规则3:注释应与其描述代码位置相邻,放在所注释代码上方或右方(不推荐右方),并与代码采用同样缩进。
大部分注释应放在代码上方,变量、枚举的注释可选择在代码右方。
建议1:不要用注释保留废弃代码
用注释保留大量废弃的代码,对阅读是一种干扰。
现代的配置管理工具能恢复任意历史时刻的代码,因此不必担心无法恢复。
建议2:不要用注释记录修改日志
代码中充斥着大量修改历史信息,使代码难以阅读。
现代的管理配置工具能记录每次修改的日志,因此不必将修改日志写在代码中。