面向对象的思考过程（原书第5版）

5.4.1　记录类并使用注释

在每个关于编程的书籍和文章、每次代码审查以及每次对优秀设计的讨论中都有关于注释和文档的主题。不幸的是，注释和优秀的文档往往不受重视，甚至更糟的是完全被忽略。

大多数开发人员知道应该始终对代码添加文档描述，但通常并不想花时间这样干。然而，如果没有优秀的文档实践是不可能驱动出优秀的设计的。在类级别，范围可能足够小，开发者可以侥幸远离劣质文档。然而，当类被传递给其他人进行扩展和（或）维护时，它可能会变成一个更大的系统（这种情况很常见），缺失正确的文档和注释会破坏整个系统。

前人已经讲过这些。优秀设计的最重要的方面之一是，设计类时应该小心地记录过程。譬如Java和.NET的实现提供了特殊的注释语法来帮助文档化过程。请看第4章来查看相应的语法。

太多的文档

请注意，注释过多也可能是个问题。太多的文档和（或）注释会成为背景噪声，而且可能会背离文档本来的目的。就像优秀的类设计一样，保持文档和注释简单易懂。编写规范的代码，本身就是最好的注释。