software camp——编程规范：注释

原则：尽量用代码来解释自己

我们必须认识到，写注释从某种意义上来说是一种“失败”，是我们无法用代码来解释意图而必须借助于注释。因此在写注释前要慎重思考，看能否通过改善代码可读性来避免写注释。

规则1：注释应解释代码的意图，而不是描述代码怎么做的

规则2：保证注释与代码一致，避免产生误导

注释造成误导，危害性很大，还不如不写。很多误导的产生，并不是有意为之，而是在代码修改的同时没有修改对应的注释造成的。因此，如果写了注释就要保证注释与代码的一致性，避免产生误导。如果注释不再有用，必须删除。

规则3：注释应与其描述代码位置相邻，放在所注释代码上方或右方（不推荐右方），并与代码采用同样缩进。

大部分注释应放在代码上方，变量、枚举的注释可选择在代码右方。

建议1：不要用注释保留废弃代码

用注释保留大量废弃的代码，对阅读是一种干扰。

现代的配置管理工具能恢复任意历史时刻的代码，因此不必担心无法恢复。

建议2:不要用注释记录修改日志

代码中充斥着大量修改历史信息，使代码难以阅读。

现代的管理配置工具能记录每次修改的日志，因此不必将修改日志写在代码中。