第 15 章 先写评论
在完成编码和单元测试之后，许多开发人员推迟编写文档，直到开发过程结束。这是产生质量差的文档的最可靠方法之一。编写注释的最佳时间是在过程开始时。首先编写注释使文档成为设计过程的一部分。这不仅可以产生更好的文档，还可以产生更好的设计，并使编写文档的过程更加愉快。
15.1 评论延迟是不好的评论
我见过的几乎每个开发人员都会推迟发表评论。当被问及为什么不更早编写文档时，他们说代码仍在更改。他们说，如果他们尽早编写文档，则必须在代码更改时重新编写文档。最好等到代码稳定下来。但是，我怀疑还有另一个原因，那就是他们将文档视为繁琐的工作。因此，他们尽可能地推迟了。
不幸的是，这种方法有几个负面影响。首先，延迟文档通常意味着根本无法编写文档。一旦开始延迟，就容易再延迟一些。毕竟，代码将在几周后变得更加稳定。到了代码毫无疑问地稳定下来的时候，代码已经很多了，这意味着编写文档的任务变得越来越庞大，吸引力也越来越小。从来没有一个方便的时间可以停下来几天并填写所有遗漏的注释，并且很容易使该项目的最佳选择合理化，那就是继续并修复错误或编写下一个新功能。这将创建更多未记录的代码。
即使你有自律性回去写评论(不要欺骗你自己:你可能没有)，评论也不会很好。在这个过程的这个时候，你已经在精神上离开了。在你的脑海中，这段代码已经完成了;你急于开始下一个项目。你知道写评论是正确的事情，但它没有乐趣。你只想尽快度过难关。因此，您可以快速地浏览代码，添加足够的注释以使其看起来令人满意。到目前为止，您已经有一段时间没有设计代码了，所以您对设计过程的记忆变得模糊了。您在编写注释时查看代码，因此注释重复了代码。即使您试图重构代码中不明显的设计思想，也会有您不记得的事情。因此，这些评论忽略了他们应该描述的一些最重要的事情。
15.2 首先写评论
我使用一种不同的方法来编写评论，在开始时就写评论：
- 对于新类，我首先编写类接口注释。
- 接下来，我为最重要的公共方法编写接口注释和签名，但将方法主体保留为空。
- 我对这些评论进行了迭代，直到基本结构感觉正确为止。
- 在这一点上，我为类中最重要的类实例变量编写了声明和注释。
- 最后，我填写方法的主体，并根据需要添加实现注释。
- 在编写方法主体时，我通常会发现需要其他方法和实例变量。对于每个新方法，我在方法主体之前编写接口注释。例如变量，我在编写变量声明的同时填写了注释。
代码完成后，注释也将完成。从来没有积压的书面评论。
评论优先的方法具有三个好处。首先，它会产生更好的评论。如果您在设计课程时写评论，那么关键的设计问题将在您的脑海中浮现，因此很容易记录下来。最好在每个方法的主体之前编写接口注释，这样您就可以专注于方法的抽象和接口，而不会因其实现而分心。在编码和测试过程中，您会注意到并修复注释问题。结果，评论在开发过程中得到了改善。
15.3 评论是一种设计工具
在开始时编写注释的第二个也是最重要的好处是可以改善系统设计。注释提供了完全捕获抽象的唯一方法，好的抽象是好的系统设计的基础。如果您在一开始就写了描述抽象的注释，则可以在编写实现代码之前对其进行检查和调整。要写一个好的评论，您必须确定一个变量或一段代码的本质：这件事最重要的方面是什么？在设计过程的早期进行此操作很重要；否则，您只是在破解代码。
评论是复杂煤矿中的金丝雀。如果方法或变量需要较长的注释，则它是一个危险信号，表明您没有很好的抽象。请记住，在第 4 章中，类应该很深：最好的类具有非常简单的接口，但可以实现强大的功能。判断接口复杂性的最佳方法是从描述接口的评论中进行。如果某个方法的接口注释提供了使用该方法所需的所有信息，并且又简短又简单，则表明该方法具有简单的接口。相反，如果没有冗长而复杂的注释无法完全描述一个方法，则该方法具有复杂的接口。您可以将方法的接口注释与实现进行比较，以了解该方法的深度：如果接口注释必须描述实现的所有主要功能，则该方法很浅。同样的想法也适用于变量：如果要花很长的时间来完整描述一个变量，那是一个危险信号，表明您可能没有选择正确的变量分解。总体而言，编写注释的行为使您可以及早评估设计决策，以便发现并解决问题。
危险信号
描述方法或变量的注释应该简单而完整。如果您发现很难写这样的评论，则表明您所描述的内容的设计可能存在问题。
当然，如果评论完整而清晰，那么它们仅是复杂性的良好指标。如果编写的方法接口注释未提供调用该方法所需的全部信息，或者编写的注释过于神秘以至于难以理解，则该注释不能很好地衡量该方法的深度。
15.4 早期评论很有趣
尽早编写评论的第三个也是最后一个好处是，它使编写评论更加有趣。对我来说，编程中最有趣的部分之一是新类的早期设计阶段，在那里，我将充实该类的抽象和结构。我的大部分评论都是在此阶段编写的，这些评论是我记录和测试设计决策质量的方式。我正在寻找可以用最少的词来完整而清晰地表达的设计。注释越简单，我对设计的感觉就越好，因此找到简单的注释是一种自豪感。如果您是策略性编程，而您的主要目标是一个出色的设计，而不仅仅是编写有效的代码，那么编写注释应该很有趣，因为这是您确定最佳设计的方式。
15.5 早期评论是否昂贵？
现在，让我们重新讨论延迟注释的参数，这是因为它避免了在代码演变时重新处理注释的开销。一个简单的信封计算将显示这并不能节省很多。首先，估算您一起键入代码和注释所花费的开发时间的总和，包括修改代码和注释的时间；这不太可能超过所有开发时间的 10％。即使您的全部代码行中有一半是注释，编写注释也可能不会占开发总时间的 5％以上。将评论延迟到最后只会节省其中的一小部分，这不是很多。
首先编写注释将意味着在开始编写代码之前，抽象将更加稳定。这可能会节省编码时间。相反，如果您首先编写代码，则抽象可能会随代码的发展而变化，与注释优先方法相比，将需要更多的代码修订。当您考虑所有这些因素时，可能首先整体编写注释可能会更快。
15.6 结论
如果您从未尝试过先编写注释，请尝试一下。坚持足够长的时间来习惯它。然后考虑它如何影响您的评论质量，设计质量以及软件开发的整体乐趣。在尝试了一段时间之后，让我知道您的经历是否与我的相符，以及为什么或为什么不这样。