16.2 维护注释：让注释靠近代码

当你改变现有的代码时，很有可能这些变更会使一些现有的注释失效。当你修改代码时，很容易忘记更新注释，这导致注释不再准确。不准确的注释让读者感到沮丧，如果有很多这样的注释，读者就会开始不相信所有的注释。幸运的是，只要有一些规范和一些指导性的规则，有可能不需要付出巨大的精力就能保持注释的更新。本节及之后的几小节提出了一些具体的技巧。

确保注释得到更新的最好方法是把它们放在靠近它们所描述的代码的地方，这样开发人员在修改代码时就会看到它们。一个注释离它的相关代码越远，它就越不可能被正确地更新。例如，一个方法的接口注释最好放在代码文件中，紧挨着该方法的主体。对方法的任何修改都会涉及这段代码，所以开发者很可能会看到接口注释，并在需要时更新它们。

对于像C和C++这样代码文件和头文件分开的语言来说，一种备选方案是将接口注释放在.h文件中方法声明的旁边。然而，这与代码相距甚远；开发人员在修改方法的主体时不会看到这些注释，而且需要额外的工作来打开不同的文件并找到接口注释来更新它们。有些人可能会争辩说，接口注释应该放在头文件中，这样用户就可以学习如何使用一个抽象概念，而不必去看代码文件。然而，用户应该既不需要阅读代码文件也不需要阅读头文件；他们应该从Doxygen或Javadoc等工具编译的文档中获取信息。此外，许多集成开发环境会提取并向用户展示文档，例如在输入方法的名称时显示该方法的文档。考虑到这样的工具，文档应该放在对从事代码工作的开发人员来说最方便的地方。

在编写实现注释时，不要把整个方法的所有注释放在方法的顶部。把它们分散开来，把每个注释压缩到最窄的范围，让它只覆盖自己涉及的所有代码。例如，如果一个方法有三个主要阶段，不要在方法的顶部写一个注释来详细描述所有的阶段。相反，为每个阶段写一个单独的注释，并将该注释放在该阶段第一行代码的正上方。另一方面，在方法实现的顶部写一个注释，描述整体策略，也是很有帮助的，比如这样：

// We proceed in three phases:
// Phase 1: Find feasible candidates 
// Phase 2: Assign each candidate a score 
// Phase 3: Choose the best, and remove it

额外的细节可以在每个阶段的代码上方记录下来。

一般来说，注释离它所描述的代码越远，它就应当越抽象（这样可以降低注释因代码发生变动而失效的可能性）。