97-things-every-programmer-should-know-16: 代码注释

仅仅让程序实现功能是远远不够的，编码的核心是要让下一个读你代码的人能顺利理解你的代码。

代码注释不是无用的，他们和编码中基本的分支，循环等一样重要。大多数的现代开发语言都有类似javadoc的工具，能自动解析注释并生成API文档。这是一个好的开始，但还不够。在代码的内部需要解释代码做了什么。 一个关于编码的古老格言：“如果代码难写，那一定难读”。

另一方面，也不能走另一个极端，即做了过多的注释。确保注释能澄清代码而不是造成混淆。 代码头部的注释应该能让读它的人足够理解代码块的意图而不需要读取具体的代码行。而行内的注释需要足够详细，能让接下来修改bug或扩展功能的开发人员容易理解。

小结

良好的代码注释和实现功能的代码本身一样重要，因为维护代码的工作时间远远大于编写新代码的工作时间。