高枝个人博客 土木读研 · 计算机 × 土木的交叉笔记
返回列表

一个人写项目,也要写文档:我的三级文档体系

「等做完了再补文档」是最大的自欺欺人。这篇讲我给自己搭的三级文档结构,以及为什么 README 永远是最不值钱的那一级。

我曾经维护过一个"三个月内写了两万行代码、零文档"的项目。后来要交付,接手的人问的第一个问题是"这个 magic number 是干什么的",我答不上来。

那次的返工花了两周。

从那之后我给自己的项目定了三级文档体系,写完就跟着代码走,不留到最后。

L0:README —— 给陌生人的第一扇门

README 的唯一任务是让人在 60 秒内决定要不要继续看。

所以它必须有:

markdown
# 项目名

一句话说清它解决什么问题(不是它是什么)。

## 快速开始
bash
npm install && npm run dev
markdown
## 它能做什么
- 能力 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);

后者半年后依然有用。