先写注释

在完成编码和单元测试之后，许多开发人员推迟编写文档，直到开发过程结束。这是产生质量差的文档的最可靠方法之一。编写注释的最佳时间是在过程开始时。首先编写注释使文档成为设计过程的一部分。这不仅可以产生更好的文档，还可以产生更好的设计，并使编写文档的过程更加愉快。

迟到的注释不是好注释

我见过的几乎每个开发人员都会推迟编写注释。当被问及为什么不更早编写文档时，他们说代码仍在更改。他们说，如果他们尽早编写文档，则必须在代码更改时重新编写文档。最好等到代码稳定下来。但是，我怀疑还有另一个原因，那就是他们将文档视为繁琐的工作。因此，他们尽可能地推迟了。

不幸的是，这种方法有几个负面影响。首先，延迟文档通常意味着根本无法编写文档。一旦开始延迟，就容易再延迟一些。毕竟，代码将在几周后变得更加稳定。到了代码毫无疑问地稳定下来的时候，代码已经很多了，这意味着编写文档的任务变得越来越庞大，吸引力也越来越小。从来没有一个方便的时间可以停下来几天并填写所有遗漏的注释，并且很容易使该项目的最佳选择合理化，那就是继续并修复错误或编写下一个新功能。这将创建更多未记录的代码。

即使你有自律性回去写注释(不要欺骗你自己:你可能没有)，注释也不会很好。在这个过程的这个时候，你已经在精神上离开了。在你的脑海中，这段代码已经完成了;你急于开始下一个项目。你知道写注释是正确的事情，但它没有乐趣。你只想尽快度过难关。因此，您可以快速地浏览代码，添加足够的注释以使其看起来令人满意。到目前为止，您已经有一段时间没有设计代码了，所以您对设计过程的记忆变得模糊了。您在编写注释时查看代码，因此注释重复了代码。即使您试图重构代码中不明显的设计思想，也会有您不记得的事情。因此，这些注释忽略了他们应该描述的一些最重要的事情。

首先写注释

我使用一种不同的方法来编写注释，在开始时就写注释：

• 对于新类，我首先编写类接口注释。
• 接下来，我为最重要的公共方法编写接口注释和签名，但将方法主体保留为空。
• 我对这些注释进行了迭代，直到基本结构感觉正确为止。
• 在这一点上，我为类中最重要的类实例变量编写了声明和注释。
• 最后，我填写方法的主体，并根据需要添加实现注释。
• 在编写方法主体时，我通常会发现需要其他方法和实例变量。对于每个新方法，我在方法主体之前编写接口注释。例如变量
• 我在编写变量声明的同时填写了注释。

代码完成后，注释也将完成。从来没有积压的书面注释。注释优先的方法具有三个好处。首先，它会产生更好的注释。如果您在设计课程时写注释，那么关键的设计问题将在您的脑海中浮现，因此很容易记录下来。最好在每个方法的主体之前编写接口注释，这样您就可以专注于方法的抽象和接口，而不会因其实现而分心。在编码和测试过程中，您会注意到并修复注释问题。结果，注释在开发过程中得到了改善。

注释是一种设计工具

在开始时编写注释的第二个也是最重要的好处是可以改善系统设计。注释提供了完全捕获抽象的唯一方法，好的抽象是好的系统设计的基础。如果您在一开始就写了描述抽象的注释，则可以在编写实现代码之前对其进行检查和调整。要写一个好的注释，您必须确定一个变量或一段代码的本质：这件事最重要的方面是什么？在设计过程的早期进行此操作很重要；否则，您只是在破解代码。

注释是复杂煤矿中的金丝雀。如果方法或变量需要较长的注释，则它是一个危险信号，表明您没有很好的抽象。请记住，类应该很深：最好的类具有非常简单的接口，但可以实现强大的功能。判断接口复杂性的最佳方法是从描述接口的注释中进行。如果某个方法的接口注释提供了使用该方法所需的所有信息，并且又简短又简单，则表明该方法具有简单的接口。相反，如果没有冗长而复杂的注释无法完全描述一个方法，则该方法具有复杂的接口。您可以将方法的接口注释与实现进行比较，以了解该方法的深度：如果接口注释必须描述实现的所有主要功能，则该方法很浅。同样的想法也适用于变量：如果要花很长的时间来完整描述一个变量，那是一个危险信号，表明您可能没有选择正确的变量分解。总体而言，编写注释的行为使您可以及早评估设计决策，以便发现并解决问题。

描述方法或变量的注释应该简单而完整。如果您发现很难写这样的注释，则表明您所描述的内容的设计可能存在问题。当然，如果注释完整而清晰，那么它们仅是复杂性的良好指标。如果编写的方法接口注释未提供调用该方法所需的全部信息，或者编写的注释过于神秘以至于难以理解，则该注释不能很好地衡量该方法的深度。

早期注释很有趣

尽早编写注释的第三个也是最后一个好处是，它使编写注释更加有趣。对我来说，编程中最有趣的部分之一是新类的早期设计阶段，在那里，我将充实该类的抽象和结构。我的大部分注释都是在此阶段编写的，这些注释是我记录和测试设计决策质量的方式。我正在寻找可以用最少的词来完整而清晰地表达的设计。注释越简单，我对设计的感觉就越好，因此找到简单的注释是一种自豪感。如果您是策略性编程，而您的主要目标是一个出色的设计，而不仅仅是编写有效的代码，那么编写注释应该很有趣，因为这是您确定最佳设计的方式。

早期注释是否昂贵？

现在，让我们重新讨论延迟注释的参数，这是因为它避免了在代码演变时重新处理注释的开销。一个简单的信封计算将显示这并不能节省很多。首先，估算您一起键入代码和注释所花费的开发时间的总和，包括修改代码和注释的时间；这不太可能超过所有开发时间的 10％。即使您的全部代码行中有一半是注释，编写注释也可能不会占开发总时间的 5％以上。将注释延迟到最后只会节省其中的一小部分，这不是很多。

首先编写注释将意味着在开始编写代码之前，抽象将更加稳定。这可能会节省编码时间。相反，如果您首先编写代码，则抽象可能会随代码的发展而变化，与注释优先方法相比，将需要更多的代码修订。当您考虑所有这些因素时，可能首先整体编写注释可能会更快。