Simon Smart 在 2025 年 11 月 26 日写下一句切中行业痛处的断言：现代开发者在代码里“寻路”所耗费的时间，已经远超真正改写代码的时间。软件工程过去几十年来视解耦为圭臬，不遗余力地消灭纠缠不清的面条代码，换来的却是彼此自治、靠异步消息连接的馄饨代码。当开发者一头扎进发布订阅模式与事件总线构筑的系统时，原先有迹可循的调用链路已被切碎，只剩下一座静态工具根本无法理清的运行时迷宫。
解耦本来是为了卸下模块间的依赖负荷，但在执行层面，它把原本由显式语法写明的先后因果，全部推给了隐式环境。
自解释神话与破地图陷阱
伴随解耦潮流而来的，是整洁代码运动对自解释代码的推崇。不少工程师由此走向极端，主张代码即文档并排斥一切注释，认为需要写注释本身就是坏味道。
这种设想低估了隐式架构对心智模型的破坏。Tenny 早在 1988 年的因子实验中就已发现，注释对那些缺乏模块化设计的差代码改善最为显著，而在高度规范的小型模块里边际收益则迅速递减。换言之，注释的价值强依赖于代码结构本身。当系统被拆散为成百上千个微小自治体，单看任何一段局部代码都干净利落，但拼装后的全局意图却彻底隐形了。
Simon Smart 为此提出补救方案：开发者必须在代码里留下路标（注释），在系统层绘制地图（架构文档）。他甚至坚持，在迷宫中摸索时，一张破旧过时的残图也远好于毫无指引。
抱残守缺的过时指引，往往比彻底空白更容易把系统引向深渊。
这个看似符合直觉的经验主义假设，经不起实证检验。Woodfield、Dunsmore 和 Shen 在 1981 年针对 48 名资深程序员进行受控实验时，带有注释的程序确实显著拿下了更高的代码理解度得分。但后来的开发环境早已改变：2019 年一项覆盖 277 名专业开发者的大型实验表明，在常规编程任务中，良好的标识符命名对理解的贡献度早已超过了形式化注释。
更反直觉的结论来自 2026 年 3 月 14 日发表的一项眼动追踪研究。研究人员追踪了 20 名计算机专业学生阅读 12 个 Java 代码片段的眼动轨迹，发现注释对代码理解速度与准确率的影响并不是稳步提升，而是在下降 30% 到提升 34% 之间剧烈震荡。不恰当的注释直接吸收了高达 23% 的视觉注视点，逼迫开发者陷入机械的线性逐行阅读，打乱了全局浏览节奏。更讽刺的是，开发者主观上觉得有用的注释，客观测试却证明它严重拖慢了理解。
宏观文档的处境同样残酷。一项面向 440 多名专业开发者的实地调查显示，文档缺失设计意图解释与真实场景案例，是上手外部组件时最坚固的障碍。而另一份针对 323 名软件从业者的调研更是指出，文档的含糊不清与事实错误不仅消耗精力，还直接导致大量开发者彻底放弃原本选定的 API 转向竞品。写错的地图，比没有地图更有杀伤力。
自动绘图工具的商业溃退
既然人工撰写维护路标与地图成本高昂且充满陷阱，为什么软件工程界没有普遍采纳自动代码地图？
这个领域的商业化退潮给出了现实回答。主打交互式可视化依赖图与代码审查地图的初创产品 CodeSee，在经历独立探索的困局后，最终在 2024 年 5 月 14 日被开发者工具厂商 GitKraken 正式收购收编。另一边，在评测网站 G2 上凭借 27 条评价拿下 4.4 分（满分 5 分）的文档工具 Swimm，也早已悄然调转船头，不再向主流互联网团队推销通用代码地图，而是将商业重心转向大型机系统，为运行着 COBOL、CICS 和 PL/I 的陈旧企业资产提供逆向工程与系统理解。至于深耕代码搜索的 Sourcegraph，则将其代码导航与跨仓库所有权追踪的能力，全部塞进企业级 Cody 企业版中变现。
- 风险.纯静态依赖关系图除了在汇报中赏心悦目，在日常代码审查与排错中极易沦为摆设，其信息密度远远低于工程直觉。
这个格局揭示了当前技术的死角：算法能轻易解析出语法树并画出函数依赖关系，但它画不出架构背后的权衡因果。机器知道 A 调用了 B，却无法推断出当初为什么要通过异步发布订阅切断这次调用。
重塑路标的工程边界
现代软件开发早已过了单打独斗的时代。在代码迷宫中跋涉，盲目冲撞是巨大的劳动力浪费，而指望靠堆砌解释代码做了什么的废话注释同样南辕北辙。
真正能穿透认知迷雾的工程约定，必须重塑路标与地图的权责。注释不该再复述变量自增或调用了哪个接口，而应当只记录代码去向、调用来源以及为什么放弃了常规方案。系统图谱也不需要事无巨细地穷尽所有边缘分支，把高频交互边界与跨模块契约描绘清楚，就已经完成了关键使命。
- 建议.当同行在代码评审中抛出困惑时，不要只在聊天框里解答，那正是必须在代码原地补上一处意图路标的明确信号。