一、笔记背景
你是否有过这样的烦恼：接手老项目，只能从代码熟悉逻辑，代码宏大如屎山；新写代码，写到一半发现不对，返工重写；或者更严重的情况，写到一半忘记原来咋设计的。。。。读了软件设计的哲学后，才发现先写注释可以很大程度避免上述问题。注意：这里的写注释不是AI自动填写，而是自己写的。
二、为什么先写
1、晚写的注释不是好注释
几乎每个开发人员都会推迟编写注释（最近一段时间不少同事直接用AI自动补充）。当被问及为什么不更早编写文档时，他们说代码仍在更改。他们说，如果他们尽早编写文档，则必须在代码更改时重新编写文档。最好等到代码稳定下来。但是，我怀疑还有另一个原因，那就是他们将文档视为苦差事。因此，他们尽可能地推迟了。
2、早期注释实际很有趣
它使编写注释更加有趣。对我来说，编程中最有趣的部分之一是新类的早期设计阶段，我在这个阶段充实类的抽象和结构。我的大部分注释都是在此阶段编写的，这些注释是我记录和测试设计决策质量的方式。我正在寻找可以用最少的词来完整而清晰地表达的设计。注释越简单，我对设计的感觉就越好，因此找到简单的注释是一种自豪感。如果您是策略性编程，而您的主要目标是一个出色的设计，而不仅仅是编写有效的代码，那么编写注释应该很有趣，因为这是您确定最佳设计的方式。
3、注释是一种设计工具，减少返工
最重要的好处是可以改善系统设计。注释提供了完全捕获抽象的唯一方法，好的抽象是好的系统设计的基础。如果您在一开始就写了描述抽象的注释，则可以在编写实现代码之前对其进行检查和调整。要写一个好的注释，您必须确定一个变量或一段代码的本质：这件事最重要的方面是什么？在设计过程的早期进行此操作很重要；否则只是代码简单堆砌，成为屎山的前奏。
注释是复杂煤矿中的金丝雀。如果方法或变量需要较长的注释，则它是一个危险信号，表明您没有很好的抽象。如果某个方法的接口注释提供了使用该方法所需的所有信息，并且又简短又简单，则表明该方法具有简单的接口。相反，如果没有冗长而复杂的注释无法完全描述一个方法，则该方法具有复杂的接口。如果要花很长的时间来完整描述一个变量或者方法，那是一个危险信号，表明您可能没有选择正确的变量分解或者方法。总体而言，编写注释的行为使您可以及早评估设计决策，以便发现并解决问题。
描述方法或变量的注释应该简单而完整。如果您发现很难写这样的注释，则表明您所描述的内容的设计可能存在问题。
4、先写注释不会占用太多时间
一个简单的粗略计算会表明这并没有节省多少。首先，估算您一起键入代码和注释所花费的开发时间的总和，包括修改代码和注释的时间；这不太可能超过所有开发时间的 10％。即使您的全部代码行中有一半是注释，编写注释也可能不会占开发总时间的 5％以上。将注释延迟到最后只会节省其中的一小部分，这不是很多。
首先编写注释将意味着在开始编写代码之前，抽象将更加稳定。这可能会节省编码时间。相反，如果您首先编写代码，则抽象可能会随代码的发展而变化，与注释优先方法相比，将需要更多的代码修订。当您考虑所有这些因素时，首先编写注释可能总体上更快。
三、怎么先写
- 对于新类，我首先编写类接口注释。
- 接下来，我为最重要的公共方法编写接口注释和签名，但将方法主体保留为空。
- 我对这些注释进行了迭代，直到基本结构感觉正确为止。
- 此时我为类中最重要的类实例变量编写了声明和注释。
- 最后，我填写方法的主体，并根据需要添加实现注释。
- 在编写方法主体时，我通常会发现需要其他方法和实例变量。对于每个新方法，我在方法主体之前编写接口注释。对于每个变量，我在编写其声明的同时填写了注释。
