8.4.2 自动生成工程文档

文档摘要

8.4.2 自动生成工程文档在工程软件开发的漫长演进中，文档始终是一柄双刃剑：它既是系统可维护性的基石，又是团队生产力的隐形枷锁。我们曾无数次在晨会中听见这样的叹息：“接口改了，但 Swagger 没更新”“这个模块的时序逻辑只在我脑子里，没人敢动”“新同事入职三天，还在翻三年前的 Word 文档找部署步骤”。这些声音背后，不是懒惰，而是文档与代码的天然异步性——代码是活的、迭代的、被测试驱动的；而文档是静的、滞后的、常由人脑临时补全的。当系统复杂度越过某个临界点（经验表明，约 5 万行核心业务代码 + 3 个以上跨域服务），手工维护文档便不再是“不够好”，而是“不可行”。 8.4.2 节所指的“自动生成工程文档”，绝非简单地将注释拼成 HTML 页面，也不是用命令走个过场。