写文档比写代码更值得练

一个反直觉的观察

同样一个功能，有人写出来三个月后没人敢改，有人写出来半年后新人能独立维护。

差别不在代码质量——两人的实现看起来差不多——而在有没有写清楚「为什么这么做」。

代码能表达「怎么做」，表达不了「为什么不那么做」。而后者才是维护时最需要的信息。

四个层次，缺一不可

第一层：是什么。 一句话说清楚这个模块/服务解决什么问题。写不出这一句，通常说明设计还没想清楚。

第二层：怎么用。 最小可运行示例。不是 API 列表，是「复制粘贴就能跑」的完整例子。

第三层：为什么。 为什么选这个方案，放弃了哪些备选，边界在哪。这层最容易省略，也最有价值。

第四层：出问题怎么办。 常见错误的排查路径、回滚方式、需要看哪几个指标。

多数团队的文档只有第二层（API 文档），所以新人遇到问题时仍然要问人。

README 该写什么

一个项目的 README，按顺序：

1. 一句话定位：这是什么，给谁用；
2. 快速开始：三条命令能跑起来；
3. 环境要求：Node 版本、依赖服务、必需的环境变量；
4. 目录结构：主要目录是干什么的（三五行，不要全列）；
5. 常见任务：怎么跑测试、怎么发布、怎么加一个页面；
6. 已知限制：什么情况会出问题。

不需要写「项目介绍」这种空话。读 README 的人只有两个目的：能不能用和怎么用起来。

注释：解释为什么，不解释是什么

// ❌ 重复代码已经说过的
// 把 count 加 1
count++

// ✅ 解释不明显的决策
// 这里必须 +1，因为下游分页从 1 开始而数组下标从 0 开始
count++

判断标准：注释应该回答「为什么不是另一种写法」。如果代码本身已经清楚，注释只会增加维护负担——改了代码忘了改注释，比没有注释更糟。

有三类地方值得写注释：

• 违反直觉的实现（看起来能简化，其实不能）；
• 外部约束（某个 API 的怪异行为、浏览器兼容）；
• 临时方案（TODO，附上什么时候能删）。

决策记录：最被低估的文档

一个架构决策，半年后一定会有人问「为什么当初这么做」。

如果没有记录，答案通常是「不知道，一直这样」，然后有人重新踩一遍当初踩过的坑。

一份轻量的决策记录，只需要四行：

## 2026-11-01 用 SQLite 而不是 PostgreSQL

背景：单机部署，数据量 < 1GB，运维人力为零。
决定：SQLite + WAL。
放弃：PostgreSQL（需要独立进程与备份策略）。
代价：并发写入受限，未来迁移需要改驱动层。

写在仓库里，和代码一起版本管理。不需要工具，一个 markdown 文件就够。

文档腐化的防治

文档最大的问题是会过期。三条对策：

一是就近放置。 接口文档放在接口代码旁边，部署文档放在部署脚本旁边。离得远，改的时候想不起来。

二是减少必须手工维护的文档。 能从代码生成的（API schema、数据库结构、配置项列表），就不要手写。

三是明确负责人。 每份文档有一个 owner，改动相关代码时由他确认文档是否还准确。

做不到第三条，前两条也会慢慢失效。

写文档的三个技巧

先写「读者要做什么」。 不是「这个模块有哪些函数」，是「你想完成 X，按这三步走」。前者是字典，后者是教程，人们需要的是后者。

用具体的例子代替抽象描述。 「支持多种格式」不如「支持 JSON、CSV、Markdown 三种，示例见下」。

删掉所有「很简单」「只需」这类词。 对写的人简单，对读的人不一定。这类词只会让卡住的人觉得自己笨。

收尾

写文档不是额外工作，它是把思考过程外化。

一个写不清楚的模块，往往是设计本身有问题——写文档的过程会逼你发现「这个参数到底该不该存在」「这两种情况为什么行为不一致」。

所以写文档的收益不只是「方便别人」，更是「逼自己想清楚」。

文档的读者只有三种

写之前先想清楚给谁看，否则会写成「什么都说了，但谁都用不上」。

新同事：需要「怎么把项目跑起来」和「代码大致怎么组织」。这类文档要极度具体，能复制粘贴。

未来的自己：需要「为什么这么做」。三个月后你会忘记所有上下文，只剩代码，那时唯一能救你的是当初写下的决策记录。

外部使用者：需要「能力边界」——能做什么，不能做什么，出错怎么办。这类文档要克制，不要承诺没验证过的行为。

同一份文档同时服务三种人，通常三种都服务不好。分开写，或者至少分节写。

多久更新一次

一个实用的信号：当有人问了你一个文档里应该有的问题时，立刻去补文档，而不是只回答他。

这个问题会重复出现十次。回答一次花两分钟，补文档花十分钟，但省下的是后面九次。

另一个信号是新人上手时间。如果新人独立跑起项目需要两天，说明快速开始那部分写得不够；如果一个月后还在问基础问题，说明架构说明缺失。

最后一件事

文档写完之后，找一个不了解这个模块的人，让他照着文档做一遍，你只观察不插话。

他卡住的地方，就是文档缺失的地方。这比任何自检都有效。