程序员应该避免写注释

“程序员工作效率有多高，取决于他大脑中对当前项目的熟悉程度，即变量名称、数据结构、编程接口以及工具类甚至是目录等，这些细节记住的越多，效率也越高。”

注释不是用来翻译程序代码的，用代码能说清楚的东西，就不要再用自然语言费脑子去写了，集中精力写出最优雅、质量高的代码才是首要的。这并不是说可以完全不写注释，而是说不要为了添加不必要的注释而打乱你的思路。我很赞成这两篇文章的观点《世上最糟糕的两个变量名》以及陆其明老师翻译的《避免在代码里写注释》，有一个好的变量名、方法名其实就是一段很好的注释了，并且还会“自动更新”，你不用在未来优化这段代码的时候同步更新注释。

我们写注释的目的不是说这段代码如何执行，而是想解释为什么要这么执行，这也正是与其研究代码、研究注释，不如研究写下这些代码的人，借用一下阿特伍德的博客原文中的例子：

r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );

这段代码没有注释就完全看不懂了，如果加上一点注释说明一下则效果要好得多：

// 用“牛顿-拉夫逊”近似法求解n的平方根
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );

这么一来注释的作用就完成体现出来了，但是如果不用注释呢？像这样：

private double SquareRootApproximation(n) {
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
return r;
}
System.out.println( "r = " + SquareRootApproximation(r) );

我们每个人在项目中应该都有遇到过这样的事情，与其让他写下一堆注释，不如告诉他命名的重要性，能完全、准确地描述所代表的事物，这无疑能提高整个项目的可读性。在命名方面也有一些陷阱，如果一个命名不能做到准确的命名，这就和一段错误的注释描述正确的行为一样让人更加费解，而且如果你在命名一个类时没有考虑太多，在后期发觉不好，要更换名称的时候会很麻烦，你可能要改头文件的名称、实现文件的名称，各种调用以及导入的地方，甚至是创建文件时自动生成的一点注释，就这要求我们在创建一个类和方法时，头脑中至少要对将要做的事情“优化”好几遍，能准确无误的表达自己想表达的东西，对一些人来说，这个过程会很累，但确实是有必要。

对命名使用准确的对仗词，有助于保持代码一致性，最终提高可读性。针对变量使用的对仗词：

• begin/end
• first/last
• locked/unlocked
• min/max
• next/previous
• old/new
• opened/closed
• visible/invisible
• source/target
• source/destination
• up/down
• 等

《千万不要把 bool 当成函数参数》这篇文章提出的问题很有意思，对于布尔变量，可以给布尔变量赋予隐含“真假”含义的名字。

最后，对你自己写下的代码，不要心存畏惧，不要把它尘封在那里，保持它的活跃度，在适当的时间对它进行重构，如果要问重构到什么地步，那就是：到你没时间重构为止。