一个人写项目,也要写文档:我的三级文档体系
「等做完了再补文档」是最大的自欺欺人。这篇讲我给自己搭的三级文档结构,以及为什么 README 永远是最不值钱的那一级。
我曾经维护过一个"三个月内写了两万行代码、零文档"的项目。后来要交付,接手的人问的第一个问题是"这个 magic number 是干什么的",我答不上来。
那次的返工花了两周。
从那之后我给自己的项目定了三级文档体系,写完就跟着代码走,不留到最后。
L0:README —— 给陌生人的第一扇门
README 的唯一任务是让人在 60 秒内决定要不要继续看。
所以它必须有:
markdown
# 项目名
一句话说清它解决什么问题(不是它是什么)。
## 快速开始bash
npm install && npm run devmarkdown
## 它能做什么
- 能力 1
- 能力 2
## 详细文档
- [架构说明](docs/architecture.md)
- [开发指南](docs/development.md)关键是最后一行。README 是索引,不是内容。
L1:架构说明 —— 给"我要动这块代码"的人
这份文档回答一个问题:为什么是这样,不是那样。
我最看重其中三节:
1. 系统边界图
text
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Client │────▶│ API 层 │────▶│ Service │
│ (Web/App) │ │ 鉴权/限流 │ │ 业务逻辑 │
└─────────────┘ └──────────────┘ └──────┬──────┘
│
┌────────────────────────┼────────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ MySQL │ │ Redis │ │ 对象存储 │
└────────────┘ └────────────┘ └────────────┘2. 关键决策记录(ADR)
每条决策记录四件事:背景、选项、决定、代价。
markdown
## ADR-003:为什么用 SQLite 而不是 PostgreSQL
**背景**:单机部署,读多写少,预计数据量 < 100 万行。
**选项**
- A. PostgreSQL:功能全,但需额外运维进程
- B. SQLite:零运维,功能覆盖 90%
**决定**:选 B。
**代价**
- 写入串行,高频写入场景需提前评估
- FTS5 迁移到 tsvector 时需要重写检索层代价这一栏最重要。 没有代价的决策说明没想清楚。
3. 数据流
挑一条最核心的链路,从入口到出口逐步写清,中间经过了哪些层、哪些外部依赖。这一节能救下未来无数次的排查时间。
L2:开发指南 —— 给"我要加一个新东西"的人
这份文档是清单化的,面向的是"照着做就能对"的场景:
- 新增一个 API:需要动哪些文件、加哪些校验、补哪些测试
- 加一个数据库字段:怎么写迁移、怎么回滚、兼容性怎么保证
- 发一个版本:checklist(测试 / 构建 / 数据库迁移 / 灰度 / 回滚预案)
我把它写成可勾选的清单,而不是散文:
markdown
## 发版 Checklist
- [ ] npm test 全绿
- [ ] npm run build 无 warning
- [ ] 数据库迁移已在预发环境执行并验证
- [ ] 迁移有对应的回滚脚本
- [ ] 关键监控已配置(错误率 / P99 / 队列积压)
- [ ] 回滚方案已确认,且能在 5 分钟内执行什么时候写?
不是"做完了写",而是:
| 时机 | 写什么 |
|---|---|
| 开始动手前 | 这次要解决什么问题,成功标准是什么 |
| 做完一个决策时 | ADR,一句话也要记 |
| 提 PR 时 | PR 描述里说清"为什么",这个会沉淀进 git log |
| 有人提问时 | 把答案补进文档,然后告诉对方位置 |
最后一条是最高效的:有人问你问题,就是文档缺口的准确定位。
关于代码注释
我的取舍:注释解释为什么,不解释做什么。
javascript
// ❌ 解释做了什么 —— 代码本身已经说了
// 遍历数组,把每个元素加一
const incremented = items.map(i => i + 1);
// ✅ 解释为什么 —— 代码本身说不清
// 之所以用 map 而非原地修改,是因为 items 来自 Redux store,
// 原地修改会导致 selector 的引用比较失效,触发无谓重渲染
const incremented = items.map(i => i + 1);后者半年后依然有用。