第 12 章：为何写注释

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

---

一句话总结

注释不是代码的累赘，而是抽象不可分割的一部分——没有注释，接口就不完整，读者无法在不读实现的情况下正确使用模块。

---

核心观点浓缩

• 注释即抽象：深模块靠简单接口隐藏实现；接口的语义、约束、取舍必须写在注释里
• 「注释税」是迷思：好注释降低理解成本，净效果是省时间而非费时间
• 代码只能表达怎么做，注释表达为什么、在什么前提下、调用方需知什么
• 注释与代码一样需要维护；过时注释有害，但因此删掉注释而非更新注释是错误反应
• 战略式编程要求：写模块时默认接口注释完整，而非「以后补」
• 与测试文档分工：测试展示行为实例，注释定义允许的行为空间与禁止用法

---

关键概念 / 金句

误区	正解
好代码自解释，不需注释	自解释只覆盖语法层，设计意图无法从代码读出
注释会过时	注释是设计文档，应随设计变更同步改
注释拖慢开发	缺注释导致误用与返工，长期更慢

「若抽象没有文档，它就不算完整的抽象。」

---

本章在全书中的位置

第 12 章开启可读性篇（第 12–18 章）。前 11 章讲如何把模块做深；从本章起讲如何让深模块被读懂——注释是第一道桥梁，接第 13 章「写什么」、第 15 章「先写注释」。Ousterhout 在此正面回应「代码即文档」派：深模块恰恰最依赖注释来补全接口语义。

---

个人思考与启发

插件加载器对外只暴露 loadPlugin(path)，若不注释线程亲和性与失败语义，调用方在主线程阻塞 UI 或忽略部分失败。三行接口注释比事后排查跨线程崩溃便宜得多。团队曾试行「无注释 PR 退回」，两月后新人上手时间从三周缩到十天——注释是 onboarding 成本最低的杠杆。

---

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

• 知识组合：注释把分散在作者脑中的上下文固化给后来者
• 「注释为何、而非如何」与本书一致；本书更强调注释是接口契约的一部分
• DRY 不适用于「把注释写进变量名里凑数」——命名无法替代设计说明

---

重点与注意

重点：每个 public 方法/类应有接口注释，说明用途、前置条件、副作用。
重点：反对注释的人常把坏注释（复述代码）当作全部注释——要写的是代码说不清的。
注意：注释不是推卸清晰命名的借口；好命名 + 好注释互补。
注意：团队规范应要求 PR 中新增公共 API 必带注释，与测试同级。
注意：内部 hack 也应有实现注释说明临时性与删除条件，避免「无注释 = 永久设计」。
注意：generated 绑定代码若缺语义，在封装类接口注释中补全，勿假设读 moc 输出。

---

导航：第 11 章 设计两次 · 下一篇：第 13 章 注释写什么