代码要不要写注释？

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

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

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

然而，若是代码就能代替注释，那Java标准库源码为何要写那么多注释？

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

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

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

对于一个缺乏注释的Java程序，能够分几个级别来逐渐增长注释：

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

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

总结成一句话：不必定要写注释，但必定要思考这个问题；若是不肯定，那就先写上。