我见过最漂亮的代码坟场，是一个连README都没有的仓库。测试覆盖率92%，架构分层清晰，命名规范得像教科书——但没人知道这玩意是干嘛用的。
原作者离职那天，带走了所有业务上下文。团队花了21天，从方法名和数据库字段里反推需求。代码像博物馆藏品：精致，且毫无生气。
代码的保质期，取决于文档的厚度
那个项目的讽刺之处在于，它本可以活得更久。原作者显然有能力写出可维护的代码，却假设自己会永远在场。这种假设在软件行业堪称行为艺术——平均任期18个月的行业里，写不写文档是生死问题。
我后来养了一只英国丁香色的猫。她传递需求的方式极其高效：直接坐在我要用的东西上，直到我满足她。没有歧义，没有"待补充"的注释。人类程序员真该学学这种沟通效率。
完美代码的负资产陷阱
这件事重塑了我对代码质量的判断标准。没人能理解的完美代码，价值为负。它消耗阅读时间，制造恐惧，让改动变成考古。反过来，文档完善的普通代码，至少能被安全地修改和扩展。
文档的本质是风险对冲。你写的每一行注释、每一张架构图，都是在为"明天我不在了"做准备。这不是悲观，是职业操守。
为什么聪明人总跳过这一步
我见过太多技术优秀的开发者抵触文档。理由出奇一致："代码即文档"。这话只对了一半——代码解释"怎么做"，从不解释"为什么这么做"。业务约束、历史妥协、临时方案，这些上下文只存在于人的记忆里。
另一个隐形障碍是即时反馈。写代码有编译器即时确认对错，写文档没有。它像给未来的陌生人写信，收不到回执，容易让人产生"在做无用功"的错觉。
但那个花了三周逆向工程的团队会告诉你：文档的回报是延迟的，也是巨大的。原作者如果花两天写清楚部署流程和业务边界，后来者的三周可以变成三天。
最小可行的文档策略
我不主张写论文式的文档。三个东西能救急：README说明项目是什么、怎么跑起来；关键业务决策的注释（特别是反直觉的代码）；架构图标注数据流向。
这三样不需要完美，需要存在。就像我的猫不需要修辞学，她只需要出现在正确的位置。
那个"完美代码"项目最后的结局？团队重写了一大半。不是代码不好，是理解成本超过了重写成本。原作者的技术能力被自己的沉默抵消了——这大概是工程师能遭遇的最隐蔽的职业失败。
你现在手边有没有一个"等我空了再补文档"的项目？那个"空"具体是哪一天？
热门跟贴