12.5 良好注释的好处

现在我已经讨论了（并希望能驳倒）反对写注释的论点，让我们考虑一下你将从良好注释中得到的好处。注释背后的总体想法是捕捉设计者脑海中但无法在代码中表示的信息。这些信息的范围从低层次的细节（如一个硬件的怪异行为促成了一段特别棘手的代码）直到高层次的概念（例如类的基本原理）。当其他开发者后来来做修改时，这些注释将使他们能够更快、更准确地工作。如果没有文档，未来的开发人员将不得不重新推导或猜测开发人员的原始知识；这将花费额外的时间，而且如果新的开发人员误解了原始设计者的意图，则存在出现错误的风险。即使是在原始设计者进行变更的情况下，注释也是有价值的：如果距离你上次编写某一段代码已经超过了几个星期，你会忘记原始设计的许多细节。

第二章描述了复杂性在软件系统中的三种表现方式：

• 变更放大：一个看似简单的变更需要在很多地方进行代码修改。

• 认知负荷：为了进行修改，开发者必须积累大量的信息。

• 未知的未知因素：不清楚哪些代码需要修改，或者为了进行这些修改，必须考虑哪些信息。

良好的文档有助于解决这些问题中的后两个。文档可以通过向开发者提供他们所需要的信息来减少认知负荷，并使开发者容易忽略那些不相关的信息。如果没有完备的文档，开发者可能不得不阅读大量的代码来重构设计者的想法。文档还可以通过阐明系统的结构来减少未知的未知因素，从而清楚哪些信息和代码与任何给定的变更相关。

第二章指出，复杂性的主要原因是依赖和模糊性。良好的文档可以阐明依赖关系，并填补空白以消除模糊性。

接下来的几章将向你展示如何编写良好的文档。它们还将讨论如何将编写文档整合到设计过程中，从而改善软件的设计。