代码注释与代码规范, 目的都是为了提高程序的可读性, 个人的原则是以代码规范为主, 代码注释为辅, 能用规范的变量名, 方法名等说明的问题就不需要额外的再添加代码注释.
详细说一下原因:
1. 如果你能让别人一看类名就知道这个类是干什么的, 一看方法名和参数名就知道怎么回事, 你还需要花上时间再去写和维护注释吗?
2. 软件工程和设计模式最基本的要求之一就是封装变化点, 这里的"变化点"是一个广义的概念, 类型改变, 方法执行流程改变这些叫做变化点改变. 注释呢? 代码注释也是软件中的变化点, 因为你同样要花上不菲的代价去维护你的代码注释. 如果你能将一些注释"封装"到变量名中, 在变化产生以后, 你要修改的也只是程序本身, 而不需要同时再修改注释, 一是省了精力, 二是避免了代码注释和逻辑不一致的情况. (很多程序员经常会无意的犯了只改代码不改注释的错误)
3. IDE开发环境现在是越来越好用, 重构的功能大家也会经常使用, 但很多时候重构会带来问题. 因为注释在逻辑上也是存在"引用依赖"的, 比如说你给一个方法加了注释, 同时很多地方你自己调用了这个方法, 而且为了说清楚问题, 你又不得不在调用的地方再加上这样的注释: 这个地方调用XX方法是为了配合YY方法做什么什么, 这样就糟了, 你在注释中引用了方法名, 很有可能以后当你或者别人重构了这个方法名后忘记了这个"引用注释"的存在, 从而产生问题. 所以最好的方式还是应该依靠代码规范, 清晰命名, 尽量做到不用添加注释.
总之, 代码注释是为了提高代码可读性, 提高团队交流效率, 降低维护成本的, 但这是把双刃剑, 处理不当或者过分要求就会成为严重的项目负担. 我提倡哪怕一些英文不好的程序员就算是使用中文命名, 也比起个含糊不清的名字+注释要好得多. 而对于有些数学性比较强的算法, 比如加密算法, 很多变量本身就很难用正常语言说清是干什么的, 我则建议在合适的地方写上总的理论原理之类的, 代码内部做到段落清晰即可.