80% 的文档都是无效的，所以多数情况下，程序员都不用写文档，原因如下：

• 多数文档都是代码的点缀或者静态的记录已经实现的代码，懂代码的开发人员会直接看代码，不懂代码的开发人员压根不会看。

• 写文档是一件要求极高的工作，就像测试驱动开发，在没有完成开发之前要理解它完成之后的样子。除非是逻辑复杂度极高的代码，否则都应该在实现过程中摸索和调整代码结构，这种效率反而更高。

• 服务代码常变而文档基本很少更新，程序员经常在屎上雕花，却很少有程序员帮助别人更新文档。究其原因代码是要运行的，文档不用运行，错了也没人关心。所以文档和代码牛头不对马嘴经常是喜闻乐见的事情。

然后说说咱们日常见到的几种文档

• 架构设计文档

• 概要设计文档

• 详细设计文档

• 系统部署文档

首先说说架构设计文档，在云原生微服务架构日趋成熟的今天，基本就是开箱即用，架构设计讲究的是小而美，1-2 个人完全可以控得住一个服务。一个完全成熟的架构，你拿过来写一篇文档，美其名曰：架构设计文档，你觉着有什么意义上吗？当然有些传统软件公司可以用这个来忽悠老板和甲方爸爸。

这种概要和详细设计文档最有用的部分也就是对外接口了，懂技术的人直接看代码了，谁会看一些不知所云的文档。但是接口不同，他可能要对外提供，你不可能让外人甚至第三方公司看你的代码。这个建议直接接口代码生成工具，每次 CI 过程中自动检查并更新，或者直接使用类似 pb 这种强约束的接口, 你要是用法不对当时就报错了，省的用了一段时间才发现不太对劲。不太理解某些人非要整理到 word 表格中，用的时候发现就差 url 路径没改了，坑爹没商量。

系统部署文档，这个东西真的不要再写了，不要再写了，不要再写了，云原生的编排文件了解一下。写个文档又不能自动把服务拉起来，不清楚写他的意义在哪里，有这时间不如写个自动启动脚本了。

最后文档真的就不用写了么？我上面所说的大多数情况，也有极少数人做一些领域内产品功能开发，比如金融、devops、以及基于密码学、分布式技术上层应用的开发等，这些技术的一个显著特点是基本不会变化，别人不用关心他是如何实现的，用就行了，这种东西反而要多写文档，写好文档，并且文档要作为代码的一部分进行 review、定期审核校验。

你可能觉着我在胡说八道，不写文档，你的代码以后怎么维护，谁看得懂? 写了就看得懂了？确定还用维护？就当今这个软件的就业形势，招一个人都想劈成 3 半用，正常功能都完不成，写的好么？写了用来误导别人？文档更多的应该是宁缺毋滥!

最后的最后再啰嗦几句，现在很多编程语言大多支持代码中的注释自动生成文档，如果能坚持更新注释内容不失为一个生成文档的好方法，对于初学者有一定帮助；但如果你把注释当成代码的一种补充和辅助，那就是耍小机灵了，代码都说不清楚的事，你觉着注释可以吗？

来源：云原生技术爱好者社区

链接: https://fly63.com/article/detial/11956