16.4 维护注释：避免重复

保持评论更新的第二个技巧是避免重复。如果文档是重复的，那么开发人员就很难找到并更新所有的相关副本。相反，尽量将每个设计决策精确地只记录一次。如果代码中有多个地方受到某个特定决策的影响，不要在每个地方都重复文档。相反，要找一个最明显的地方来编写文档。例如，假设有一个与变量有关的棘手的行为，它影响到使用该变量的几个不同地方。你可以在变量声明旁边的注释中记录这一行为。如果开发者在理解使用该变量的代码时遇到困难，他们自然会在这里进行检查。

如果没有一个“明显”的地方可以将某段文档放在开发者可以找到的地方，可以按照第13.7节所述，创建一个designNotes文件。或者，在现有的地方中选择一个最好的地方，把文档放在那里。此外，在其他地方添加简短的注释，以提及中心位置。“关于下面代码的解释，请参阅xyz中的注释。”如果因为主注释被移动或删除而使引用变得过时，这种不一致将是不言而喻的，因为开发人员不会在指定的地方找到注释；他们可以使用修订控制历史来查清楚注释发生了什么，然后更新引用。相反，如果文档是重复的，而其中一些副本没有被更新，那么就不会有任何迹象表明开发者在使用过时的信息。

不要把一个模块的设计决策重新记录在另一个模块中。例如，不要在一个方法的调用前加上注释，解释在被调用的方法中会发生什么。如果读者想知道，他们应该看一下该方法的接口注释。好的开发工具通常会自动提供这些信息，例如，如果你选择一个方法的名称或将鼠标悬停在该方法上，就会显示该方法的接口注释。尽量让开发者容易找到合适的文档，但不要通过重复文档来做到这一点。

如果信息已经在你的程序之外的某个地方被记录下来，不要在程序中重复这些文档；只需引用外部文档。例如，如果你写了一个实现HTTP协议的类，你就没有必要在你的代码中描述HTTP协议。网络上已经有许多关于这个文档的来源；只需要在你的代码中添加一个简短的注释，并附上这些来源的URL。另一个例子是那些已经在用户手册中记录的功能。假设你正在编写一个实现一系列命令的程序，由一个方法负责实现每个命令。如果有一本用户手册描述了这些命令，就没有必要在代码中重复这些信息。相反，在每个命令方法的接口注释中包括一个像下面这样的简短说明：

// Implements the Foo command; see the user manual for details.

重要的是，读者可以很容易地找到理解你的代码所需的所有文档，但这并不意味着你必须编写所有这些文档。