为什么我劝你尽早养成"写文档"的习惯

一、一个扎心的真相

工作第三年，我接手了一个"祖传项目"。代码能跑，但没人说得清为什么这么写。我花了整整两周，才从 git log 的只言片语里拼凑出架构意图——而原作者就在隔壁工位，他看着我苦笑："早忘了，当时赶进度没写文档。"

那一刻我突然意识到一件事：代码是写给机器执行的，文档才是写给人类理解的。

没有文档的代码，就像没有路标的迷宫。你当时走得出来，三个月后你自己都走不出来。

二、写文档不是"额外工作"，是给未来的自己买保险

很多人抗拒写文档，理由通常是这三个：

"代码即文档。"

代码能告诉你怎么做，但永远无法告诉你为什么这么做。为什么选 Redis 而不是 Memcached？为什么这个超时设的是 3 秒而不是 5 秒？为什么这里有个看似多余的 sleep(100)？这些"决策背后的故事"，代码一个字都不会说。

"写了也没人看。"

没人看，往往是因为文档写得像说明书——堆砌参数列表和目录结构。好的文档解决的是"我从哪里入手""这个设计为什么是这样""出了事我该看哪里"。这类文档，每个接手的人都会感激你。

"需求老变，写了也白写。"

那就别写"最终版文档"，写决策记录（ADR, Architecture Decision Record）。记录每一次关键决策：背景、选项、选择、后果。需求变了，决策记录就是"为什么变了"的最真实证据链。

三、我现在的文档习惯，分享给你

经过几次"接手地狱"和"被接手投诉"之后，我逐渐形成了自己的文档节奏。不需要多完美，关键是持续、轻量、有用。

1. README 是底线，不是可选项

每个项目，哪怕是一个小工具脚本，我都写 README。结构固定：

# 项目名称
一句话说清楚这是干嘛的

## 快速开始
3 步能跑起来

## 架构概览
一张图或一段话，说清核心模块关系

## 关键设计决策
为什么这么设计（最重要！）

## 常见问题
踩过的坑和对应解法

不用长篇大论，200 字也行。但要有。

2. 写"为什么"，而不是"是什么"

代码里加注释，我遵循一个原则：只解释意图，不翻译代码。

# ❌ 烂注释
# 遍历列表，过滤出大于 10 的元素
filtered = [x for x in items if x > 10]

# ✅ 好注释
# 阈值 10 来自业务方确认的"异常交易金额下限"，低于此值不触发风控
filtered = [x for x in items if x > RISK_THRESHOLD]

文档同理。多写"为什么选 A 不选 B"，少写"系统包含模块 A、模块 B、模块 C"。

3. 用"故障复盘"倒逼文档更新

每次线上出问题，复盘文档里必有一项："哪些信息如果提前写在文档里，能缩短排查时间？"​ 然后立刻补上去。

这是最自然的文档驱动方式——你刚被坑过，记忆最鲜活，补的文档也最切中要害。

4. 给自己写"交接文档"

每隔半年，我会假想"如果明天我离职，接手的人第一周会问什么"。把这些问题的答案写成文档。不是为了走，而是因为能说清楚，才说明你真的想清楚了。

四、写文档带来的意外收获

说几个我没想到但确实发生的事：

1. 写文档的过程，是最好的 code review

你以为想清楚了，一写才发现逻辑有漏洞。我至少有三次，文档写到一半发现"这里不对"，回头改了代码设计。

2. 晋升答辩时，文档是你的弹药库

"你做过什么"不是靠临场回忆的，是你平时一篇篇文档积累出来的。我去年晋升时，答辩材料 60% 的内容直接来自平时的技术文档和复盘记录。

3. 影响力从"写代码的人"变成"让人少踩坑的人"

文档被团队复用、被跨部门引用、被新人当作入门指南——这种成就感，比合入一个 PR 持久得多。

五、写在最后

我常跟新入职的同学说：

你写的每一行代码，最终都会过时。但你写下的每一个"为什么"，会在你离开很久之后，继续帮到别人。

写文档不是给领导看的，不是给绩效加分的，是给你自己、给你的继任者、给三年后回头看代码的你——留一条能走回去的路。

从今天开始，哪怕只做一件事：给你正在做的项目，补一个 README。

200 字就行。先写起来。