如何谨慎使用代码注释以避免混淆和过度注释？

本文共计1972个文字，预计阅读时间需要8分钟。

前言：最令程序员头疼的事情莫过于阅读别人的代码，但实际上时间一长，阅读自己的代码也会非常痛苦。

问题不在于自己或别人，而在于代码本身。

必要的注释可以明确实现细节和设计。

前言

最令程序员头痛的事情莫过于阅读别人的代码，但其实时间一久阅读自己的代码也会很痛苦。 问题不是出在『自己或别人』，而是在代码本身。

必要的注释可以阐明实现细节和设计意图，以此节约自己和别人的时间。 然而很多时候注释起的作用却适得其反，比如自动生成的过多的注释分散阅读者的注意力， 而过期的失效的注释更是误导阅读者。

自动生成的注释

代码注释的泛滥想必是从Eclipse，Visual Studio等IDE开始的。 这些IDE提供了很多快捷功能，生成类/接口的骨架，具有Getter/Setter的属性等等。 如果用过IDE，下面的代码你一定不会陌生：

/** * @param args */ public static void main(String[] args) { // TODO Auto-generated method stub }

上述6行代码中的4行注释包含的信息量是0，既没有阐释参数args是何物，也没有说明main的用途。 然而大量的项目中都充斥着这样的自动生成注释。

『建议』：如果有参数或机制需要说明，请补充这些信息。否则请删除自动生成注释。 当然，用于生成文档的注释除外。

过多的注释

总会有人不厌其烦地编写长篇累牍的注释，或无微不至，或语焉不详，或晦涩难懂，或文采飞扬。 总之没有帮助我更快阅读代码的注释都是失败的注释。