1、课程导论：为什么嵌入式软件需要架构文档？文档版本管理的痛点与价值
1.1 一个真实的“翻车”现场
先讲个我自己的故事。
几年前，我带团队做一款工业控制器的固件。项目赶得急，大家心照不宣地跳过了架构文档——反正代码能跑就行，对吧？
结果呢？
三个月后，客户要求增加一个传感器通道。我打开代码一看，好家伙，任务调度、中断优先级、内存池分配全揉在一个 8000 行的 main.c 里。改一个地方，崩三个功能。最后加班两周，才勉强把补丁打上。
更惨的是，半年后换了个新人接手，他对着代码完全不知道从哪里下手。问我，我也只能挠头——当初的设计思路，早忘光了。
这就是没有架构文档的代价。
一句话总结： 嵌入式软件不是“写出来”的，是“设计出来”的。没有文档，设计就只存在于你的脑子里——而脑子是会忘的。
1.2 为什么嵌入式软件尤其需要架构文档？
你可能会想：“我做桌面应用也没写架构文档，不也活得好好的？”
嗯，嵌入式不一样。说白了，嵌入式软件有三大“硬约束”：
- 资源受限： RAM 可能只有 64KB，Flash 只有 512KB。架构设计直接影响内存布局、堆栈分配、代码尺寸。
- 实时性要求： 中断响应、任务调度、时序约束——这些不是靠“优化代码”能解决的，必须在架构层面提前规划。
- 硬件耦合： 驱动、BSP、外设管理、电源管理……软件和硬件深度绑定。没有文档，换一颗 MCU 就等于重写一遍。
我见过太多团队，把精力花在“写代码”上，却忽略了“设计代码”。结果就是：
| 问题 | 没有架构文档 | 有架构文档 |
|---|---|---|
| 需求变更 | 到处打补丁，牵一发动全身 | 按模块评估影响，改一处即可 |
| 新人接手 | 看代码猜意图，效率极低 | 看文档理解设计，快速上手 |
| 代码审查 | 只能检查语法和风格 | 能检查设计是否合理 |
| 复用迁移 | 几乎不可能，只能重写 | 模块化设计，轻松移植 |
| 质量保障 | 靠个人经验，不稳定 | 靠架构约束，可预测 |
我的习惯： 每次开始一个新项目，我会先画一张“架构总览图”——哪怕只是手绘在白板上。这张图决定了后续所有代码的走向。
1.3 文档版本管理的痛点
好，你接受了“要写文档”这个观点。但下一个问题来了：文档写完了，怎么管？
我遇到过的情况，你大概率也遇到过：
- “最终版”陷阱： 文档命名从 v1.0 到 v1.8，再到 v1.8_final，再到 v1.8_final_真的不改了.docx。最后谁也不知道哪个才是对的。
- 文档与代码脱节： 代码改了三个月，文档还是半年前的版本。新来的同事照着文档写驱动，结果 API 全变了。
- 多人协作冲突： 两个人同时改了同一份架构文档，然后互相覆盖。最后只能靠“谁嗓门大听谁的”来裁决。
- 历史追溯困难： 出 bug 了，想查一下当初为什么这么设计。结果文档里没有记录任何决策理由。
这些痛点，说白了就是“版本管理缺失”的典型症状。
我曾经踩过的坑： 有一次，客户要求提供一份“架构设计说明书”。我翻遍了项目文件夹，找到了 7 个不同版本的 PDF。最后只能把所有人叫到一起，花了一整天“拼凑”出一份能交差的文档。从那以后，我强制团队使用 Git 管理文档，和代码同源。
1.4 文档版本管理的核心价值
那么，好的文档版本管理能带来什么？
- 可追溯： 每一次修改都有记录，谁改的、为什么改、改了什么，一目了然。
- 可同步： 文档和代码使用同一套版本管理工具（比如 Git），确保两者始终对齐。
- 可协作： 多人并行修改，冲突可合并，不会互相覆盖。
- 可发布： 每个版本对应一个稳定的基线，方便评审、测试和交付。
你想想看，如果代码没有版本管理，你会不会疯掉？那为什么文档就可以没有？
1.5 本章知识体系
下面这张图，概括了本章的核心逻辑：
1.6 这门课能给你什么？
这门课不是教你怎么写“漂亮的文档”。
而是教你怎么写“有用的文档”——能真正指导开发、支撑决策、降低风险的架构文档。
我们会从文档结构设计、版本管理策略、工具链搭建、评审流程、持续维护等角度，一步步带你建立起一套可落地的文档体系。
嗯，说白了，就是让你不再为“文档”这件事头疼。
一个小建议： 学完这门课，你可以先拿一个正在做的项目试试手。不用追求完美，先写一个模块的架构说明，然后看看效果。你会发现，写文档这件事，其实没那么难。