当前时间： 2026-04-24 23:32:08
更新时间： 2026-04-24
分类：软件教程
评论(0)
文档比代码多三倍,这个项目是怎么死的?
代码仓库里一共8.3万行有效代码，剔掉注释和空行大概6万出头。文档呢？
光是Word文件就有412份，打印出来摞在一起将近两米高。
那个项目最后延期了11个月，客户不满意，几个核心开发跑路了，我自己也在项目结束后请了一周病假。
军工软件有一套完整的文档体系，这套体系本身没什么问题
——需求规格、概要设计、详细设计、测试报告、验收报告，每一类都有存在的理由。
问题出在执行层面，或者更准确地说，出在”文档即工作”这个集体幻觉上。
我见过一个某型保障系统的项目，需求确认文档前后改了37版！37版！！
每一版都有完整的审批流程，每一版都有领导签字，每一版都被郑重其事地存进了文档管理系统。
需求变了就变了，反正文档和代码从第5版之后就已经对不上了，大家心照不宣地各干各的，到验收的时候再统一”对齐”一下
——说白了就是把文档改成跟代码一致，美其名曰”文档更新”。
这不是在开发软件，这是在写两套平行的小说：一套给机器跑，一套给人看。
写测试用例，搭测试环境，跑测试脚本，记录缺陷，回归验证，出测试报告。
但你去问问那些真正做过测试评审的人：评审会上，有几个人把代码打开来看了？
我不是说没有，我是说，按我自己的经历来看，十次评审里大概有八次是这样的：
测试组的同事把PPT翻到“测试通过率99.7%”那一页，现场没有人提出任何质疑，主持人说”大家没有异议的话我们就通过了”，然后在表单上签字。
我亲眼见过一个系统，核心的数据处理模块有一个边界条件bug，在特定输入下会导致结果偏差。
因为测试用例压根没有覆盖到那个边界条件，而没有人在评审会上去检查测试用例的覆盖率。
文档很有用，在正确的地方、正确的方式下，文档能救命。
但在我们这个行业，文档慢慢变成了一种自我保护机制，而不是沟通工具。
写文档的目的不再是“让下一个接手的人能看懂”，而是“如果出了问题，我有东西可以拿出来证明我做了”。
“你看，这个功能当初是你们确认过的，第23版第47页，你们领导签了字的。”
每个部门都开始用文档筑墙，每次沟通都要留痕，每个决定都要有会议纪要，每个纪要都要有签字，每个签字都要有归档。
然后大家开始抱怨进度压力，抱怨需求变更，抱怨人手不足；
没有人去抱怨那十天，因为那十天是”规范流程”，是不能质疑的。
质疑文档流程，就是不懂规矩，就是不重视质量，就是给上级审计留把柄。
有一次我跟一个做了二十年的老主任聊这个问题，他说了一句话我一直记着。
你知道为什么文档要写这么多吗？因为没有人信任任何人。
文档体系本质上是一套不信任机制——我不信任你真的理解了我的需求，所以我要写成文档让你签字；
你不信任我真的实现了你的需求，所以你要有测试文档来证明；
审计方不信任我们整个团队，所以要有全套归档来覆盖每个环节。
军工项目的特殊性决定了它必须有严格的过程管控，这个逻辑没有错。
但当过程管控异化成文档堆砌，当”有文档”等同于”做了事”，当评审签字变成走过场；
这套体系就开始消耗它本来应该保护的东西：真正在干活的人的时间和精力。
那个190万字的项目，两个最好的开发后来都离职了。
他们不是因为技术干不下去，是因为干一件事要填七张表，他们觉得自己不是在写代码，是在做文员。
我不是来喊口号的，”精简文档流程””提高文档质量”这种话谁都会说，没用。
我的建议是从自己能控制的范围做一件事：在你自己的团队内部，把文档和决策分开。
-
内部开发沟通，用一个共享的Confluence页面或者飞书文档，实时更新，不需要版本号，不需要签字，谁改谁负责，改错了回滚。
-
对外交付的文档，该有的一个不少，但那是最后的交付物，不是过程中的沟通工具。
把这两件事分开之后，你会发现内部沟通效率会明显提升
——因为大家不再需要用写文档的方式来”留证据”，直接说，直接改，直接跑通。
当然这需要团队内部建立一定的信任基础，这才是真正难的地方。
但它是可以做的，它不需要你去推动全院改制，你只需要在自己的小组里试一试。
夜雨聆风
