让文档跟着代码走

文档总是过时的

文档会腐烂。

不是因为团队懒惰。是因为熵增是自然规律。代码每天在变，文档需要人工同步。这个过程消耗能量，需要纪律，依赖记忆。任何一个环节松懈，文档就开始偏离真相。

大多数团队的应对方式是"加强文档审查"、"建立文档规范"、"定期更新文档"。这些方法试图用更多的纪律对抗熵增。

但纪律是最稀缺的资源。

真正有效的方法不是更频繁的手工维护，而是减少需要手工维护的文档数量。让文档"活"起来——跟随代码自动更新，而不是依赖人的记忆。

文档的三种生命形态

文档不是单一类型。它有三种形态，每种形态有不同的生命周期。

第一种：活文档。 它就是代码本身。函数签名、类型定义、代码注释。这些文档随代码一起编辑、一起提交、一起审查。它们永远不会过时，因为它们就是真相。

第二种：半自动文档。 它从代码生成，但需要模板和规则。API参考、数据库Schema、组件清单。这些文档由工具扫描代码自动生成。人定义生成规则，机器执行更新。

第三种：手工文档。 架构设计、部署流程、开发指南。这些文档无法从代码推导，必须由人编写。它们更新最慢，也最容易腐烂。

活文档：代码即文档

最好的文档就是代码本身。

/**
 * 计算用户的积分消耗成本
 *
 * @param credits - 用户消耗的积分数量
 * @param vendorCost - 厂商API的实际成本（美元）
 * @returns 利润率百分比
 */
function calculateProfitMargin(credits: number, vendorCost: number): number {
  const revenue = credits * 0.0483  // Pro方案单积分价值
  return (revenue - vendorCost) / revenue
}

这段代码的文档不会过时。因为函数签名、参数类型、返回值都是编译器验证的。注释紧挨着代码，修改代码时很难忽略注释。

这种文档的维护成本最低。开发者不需要额外的步骤，不需要切换到另一个文件，不需要记得"别忘了更新文档"。文档就在眼前。

但活文档有局限。它只能描述单个函数或类的行为，无法展示系统的全貌。这时需要第二层。

半自动文档：让机器做记忆的工作

当系统有50个API时，没人能记住每个API的参数和返回值。这时需要API参考文档。

但手工维护API参考是灾难。每次接口变更，都要记得更新两个地方：代码和文档。人的记忆不可靠。

解决方法是让机器扫描代码，自动生成文档。

# 代码提交时自动触发
git commit → pre-commit hook → 扫描代码 → 生成文档 → 提交文档

开发者只需要写好代码注释（活文档），工具自动汇总成API参考（半自动文档）。维护的负担减少了一半。

在Purikura项目中，我们用TypeDoc从TypeScript代码生成API文档，用脚本从数据库Schema生成表结构文档。这些文档每次提交时自动更新，开发者无需手工维护。

手工文档：不得不做的事

有些文档无法自动生成。

架构设计解释"为什么这样设计"。部署流程记录"在什么环境做什么操作"。这些知识无法从代码推导。

手工文档是必需的，但应该被最小化。

原则一：只写无法自动化的内容。 如果某个信息可以从代码生成，就不要手工编写。比如API参数列表属于半自动文档，不应该出现在架构设计文档中。

原则二：用图表代替大段文字。 一张流程图胜过一千字描述。Mermaid图表嵌入在Markdown中，修改方便，版本控制友好。就像API文档标准中的成本计算流程图。

原则三：在重大变更时强制更新。 架构变更、部署流程变更、API设计变更——这些事件必须触发文档更新。不是靠自觉，是靠流程约束。

为什么自动化优先

有人会说："写文档也没那么费时间，手工维护就好。"

问题不在时间，在可靠性。

人会忘记。人会疲倦。人会在deadline前选择跳过"非关键步骤"。文档更新就是这种"非关键步骤"——当它被跳过时，系统不会崩溃，测试不会失败，用户不会抱怨。

但文档会悄悄腐烂。三个月后，没人知道这个函数为什么这样设计。六个月后，新人看着代码和文档的差异，不知道该相信哪个。

自动化不是为了节省时间，是为了确保事情一定会发生。

就像防御式编程不是因为程序员水平差，而是承认人不可能记住所有边界条件。文档自动化不是因为团队懒，而是承认人的记忆不可靠。

文档是代码的镜像

文档不是附加物。它是系统的另一种表达。

代码描述"怎么做"，文档描述"为什么做"和"如何使用"。两者应该同步演进，而不是代码在前、文档在后。

当文档落后于代码，说明流程有问题。要么文档分类错误（应该是活文档或半自动文档，却被当成手工文档维护），要么缺少自动化工具，要么团队对文档重要性认识不足。

让文档跟着代码走，不是加强纪律，是改变系统设计。把更多文档推向活文档和半自动文档，减少手工文档的依赖。让自动化成为流程的一部分，而不是额外的负担。

文档衰败是熵增的自然结果。但熵增可以被延缓，只要你理解文档的三种形态，并为每种形态选择正确的维护策略。