第 15 章：先写注释

系列：软件设计的哲学 · 第 15/22 章
全书导读：00-overview.md

---

一句话总结

在写实现之前先写接口注释，把设计摊在纸面上——写注释的难易程度，就是接口好坏的即时反馈。

---

核心观点浓缩

• 注释先行是设计活动，不是文档事后补录；与第 11 章「设计两次」同源
• 流程：为模块写接口注释 → 发现说不清处 → 改设计 → 再写代码
• 若某方法注释需长篇解释「特殊情况」，往往是接口过宽或职责过多
• 实现阶段补实现注释；接口注释在设计阶段应已稳定
• 先写注释成本低：改几句话 vs 改几百行代码
• 可与接口评审合并：注释即评审材料，比读实现找问题早一个数量级
• 结对时一人念接口注释、一人挑刺，是「注释先行」的轻量 social 版

---

关键概念 / 金句

信号	含义
注释写不顺	抽象边界或命名有问题
注释极长	接口可能太浅或承担过多
注释为空也能懂	接口可能足够清晰（仍要补契约）

「写不出简洁的接口注释时，别开始写代码——先改设计。」

---

本章在全书中的位置

第 15 章把第 12–14 章的可读性原则嵌入设计流程，衔接前半模块篇与后半修改/一致性章。它是战略式编程（第 3 章）在文档层的具体操作：投资设计时间换长期简单。注释先行把「设计评审」前移到键盘敲实现之前，与第 11 章纸面设计两次形成双保险。

---

个人思考与启发

新做日志上传服务时，先在头文件写 /// 异步上传；失败重试 3 次；不保证顺序。写的过程中发现「顺序」与现有队列假设冲突，于是把顺序保证下沉到调用方，接口保持单一职责。若先写代码，很可能把冲突藏进 if-else。注释先行还迫使你在 PR 描述里引用同一段文字，审阅者不必从 diff 反推设计意图。此习惯对跨时区异步 Review 尤其有价值。

---

与《程序员修炼之道》对照

• 曳光弹验证需求路径；先写注释验证接口路径——可组合使用
• 原型代码可战术式；定 API 时应切到战略式 + 注释先行
• 「规范即测试」：清晰的接口注释可衍生契约测试清单

---

重点与注意

重点：新模块 PR 可先审头文件注释，再审实现——顺序颠倒则难改。
重点：与「设计两次」结合：注释方案 A/B，对比哪个更易解释。
注意：先写注释不是写废话占位；仍遵守第 13 章「不写代码已表达之物」。
注意：遗留代码大改时，也可先改注释反映目标设计，再分步改代码对齐。
注意：注释与单元测试描述冲突时，以注释 + 测试共同修正为准，勿留二义性。
注意：设计评审通过后再动接口注释，避免注释与已合并实现长期脱节。

---

导航：第 14 章 命名 · 下一篇：第 16 章 修改既有代码