很多人觉得重构就是埋头改代码，把旧逻辑理顺、函数拆清楚就完事了。可等到项目一上线，新人接手或者自己回过头看，却发现根本看不懂当初为什么这么改。这时候才想起来——文档呢？
边重构边写文档，其实最省时间
你有没有遇到过这种情况：花三天把一个烂模块重构成清晰结构，结果一周后领导问你“这块为啥要改成这样”，你愣住了。翻记录、查提交信息，还是说不清楚。其实这时候，几行注释或一段设计说明就能省去后续一堆解释成本。
重构不是单纯让代码变“好看”，而是为了让系统更容易维护。而文档，本身就是维护的一部分。你在调整函数职责、拆分类结构的时候，顺手写两句话说明动机，比事后凭记忆补全靠谱得多。
写什么？不需要长篇大论
文档不等于写论文。比如你把一个 500 行的处理函数拆成了三个小函数，可以简单记下：
// 拆分依据：原 handleOrder() 职责过多
// - extractValidateOrder()：仅做参数校验
// - extractCalculatePrice()：价格计算独立，便于测试
// - extractSendNotification()：异步通知分离，降低耦合这种记录不用发邮件、不用走流程，就放在代码注释里，或者更新一下内部 Wiki 的对应章节。下次有人想动这块代码，一眼就知道边界在哪。
团队协作时更不能省这一步
如果是一个人维护的小工具，可能靠记忆撑一阵子。但只要涉及交接、多人并行开发，文档就成了沟通桥梁。比如你重构了数据库访问层，把原来的拼接 SQL 改成 ORM 调用，如果不说明原因（比如防注入、提升可读性），别人很可能又偷偷加回字符串拼接。
更现实的情况是：你不写清楚，别人不敢动；写得太模糊，别人乱动。最后系统又慢慢回到“需要再次重构”的状态。
文档也是重构质量的一面镜子
有时候写着写着就会发现：这文档怎么写都讲不明白？那很可能说明重构还没到位。好架构通常能用简单语言说清逻辑。如果你发现自己需要用“先调这个接口再触发那个定时任务最后还得看配置开关”这种绕口令来解释流程，那就得回头看看是不是拆得还不够干净。
所以，写文档不只是记录结果，它本身也是一种检验。就像写文章，写不出来，可能是思路没理顺。
养成随手记的习惯
不用专门腾出“写文档时间”。每次提交代码前，花两分钟想想：这次改动的关键点是什么？有没有可能被人误解？把答案写进提交信息或注释里。日积月累，你会发现这个项目越来越容易掌控，而不是越改越迷糊。
重构不是一次性手术，而是一个持续改善的过程。而文档，就是这个过程中的路标。没有它，走得再快，也可能走偏。