代码要不要写注释

近年来有一种思潮，认为代码不需要注释——代码即注释。这种思潮是有一定道理的，但很多人难以正确领会。

这一思潮的兴起是由于以往提倡多写注释，很多人没能正确领会“多写注释”的意义，写了一大堆多余甚至有错误的注释：

• 当注释内容与代码内容重复时，注释就是多余的：
  // update status
  updateStatus();
• 当注释内容与代码的实际作用不一致时，注释就是错误的：
  // copy node to new position
  moveNode(node, position);

然而，如果代码就能代替注释，那 Java 标准库源码为什么要写那么多注释？

代码即注释的前提是：代码能表达充足而明确的语义，从而能替代注释的作用。这么做能反过来促进编写更加语义化的代码，改进代码质量，但是这需要代码的作者和审查者有足够好的品味。品味从哪来？多学习，多思考。不假思索地堆砌代码总是有害的。

新手在懂得不多的情况下，难以把握合适的度——注释是多写一点好还是少写一点好？多写不一定对，但是多思考一些总是没错的。新手要先学会写注释，然后才进一步去学减少不必要的注释，不要一上来就用极简风格，一行注释都没有，以致程序的意图和逻辑令人费解。

关于如何做好“代码即注释”，可参考《代码整洁之道》，有一个原则是类名、函数名和方法名要清晰表达“这是用来做什么的”而不是“这是如何实现的”，例如 save() 优于 saveToDisk()。关于如何写好注释，可参考《代码大全》。

对于一个缺少注释的 Java 程序，可以分几个级别来逐渐增加注释：

1. 类级 Javadoc，说明这个类的职责和作用，使用者要注意什么事项
2. 方法级和字段级 Javadoc，说明这个方法或字段的用法和作用，使用者要注意什么事项
3. 重要代码行的注释，说明这段代码的“目的”或“为什么写成这样”

通过这一过程，代码会变得更加易于理解。

总结成一句话：不一定要写注释，但一定要思考这个问题；如果不确定，那就先写上。