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

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

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

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

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

  • 架构设计文档

  • 概要设计文档

  • 详细设计文档

  • 系统部署文档

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

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

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

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

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

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

原创不易，随手关注或者”在看“，诚挚感谢！

程序员应该写文档吗？相关推荐

  1. 让程序员头疼的文档问题怎么破？试试活文档

    文档是程序开发过程中的蓖麻油:主管们认为它会对程序员有益,而程序员却讨厌它! --Gerald Weinberg,<程序开发心理学> 当你听到文档这个词会想到什么? 它很无聊. 要写很多字 ...

  2. 小议程序员编写技术文档

    一提到写文档,可能很多程序员可能会不屑一顾,但是,无论处于规范开发流程,还是就于逃避嫌责的目的,能够将自己所从事的工作用文档描述记录下来,还是一件很有成就感的事情,抛开其功用不谈,就个人的成长进程看, ...

  3. python开发技术文档范文_程序员编写技术文档的新手指南

    这是一篇帮助你给第一个项目写文档的指南. 万事开头难,我希望这份指南能把你引导到正确的道路上. 最后,你应该有一个可以公开发布的项目. 请轻松地阅读完这篇文章,或者简单地把它当作参考. 为什么要写文档 ...

  4. 程序猿为什么不喜欢写文档？

    公众号文章地址:程序猿为什么不喜欢写文档? 有几个事情其实一直是猿猿们内心的痛: 新入职小白 5分钟前: 这系统怎么就没有文档呢? 中级码农 4分钟前: 这代码tm居然没有注释和说明!!! 老油条程序 ...

  5. 不给代码写文档，让代码文档化

    这是程序员讨论了很久的一个话题:要不要给代码写文档?值得给代码写文档吗? 我曾经觉得这个话题实在是让人难以应付.也认为除去一些特殊的情况(比如编写公用 API),代码文档并不是那么必要.直到有一天,我 ...

  6. 为什么程序员都不写文档？

    ‍‍‍ ‍ [CSDN 编者按]对于程序员来说文档可能是他最大的软肋.一些被称之为高手的程序员,往往是文档方面的处理会偏弱.不管这个程序员是在大公司.还在小公司.不管程序是写文档的.还是不写文档的,大 ...

  7. 程序员都讨厌写文档？这4个工具让你事半功倍

    长按识别上方二维码,关注公众号:后端面试那些事 回复"报告",获取你的GitHub年度报告! 对于一般的程序员来说,花费数小时来创建代码或修改现有代码只是一天工作中的一部分,简而言 ...

  8. 从程序员到项目经理（二十九）：怎样写文档

    在软件项目中,文档既是一项的重要成果,也是项目管 理的有力工具.通过文档,可以稳定.明确的传达信息,实现项目内的有效沟通.所以写文档对项目经理来说,是一项必备的技能. 然而很多项目经理害怕写文档,似乎 ...

  9. java开发文档怎么写_程序员该不该写技术文档，怎么写文档，易懂又能提升自己...

    最近公司项目的调用量突然涨了一大波,很多系统都纷纷扛不住了,于是需要对系统进行优化,系统优化的第一步,便是梳理业务! 在这个过程中,经常出现了这样一些情况,发现数据库的某些字段,没有注释,也没有一定的 ...

  10. 程序员写文档的重要性

    写文档的重要性 对于软件相关行业,在学校或单位大家也许都已经注意到了,除了要编写的程序.绘制设计图之外,还有一个重要的工作便是写文档.为什么要写文档呢?因为我们要把自己做的东西展示出来,不光展示给同行 ...

最新文章

  1. golang append时slice len 和 cap
  2. 程序、进程、线程之间的区别
  3. python类的空间问题及类之间的关系
  4. python有什么内容_python能做什么
  5. Git-根据tag创建分支
  6. python里的拼接_Python拼接字符串的7种方法总结
  7. python中re模块_Python中re(正则表达式)模块学习
  8. 查询sql执行计划_使用SQL执行计划进行查询性能调整
  9. 计算机专业内卷严重,考研，这6个专业“内卷”严重，竞争较为激烈！
  10. Python核心编程读笔 4
  11. 小学生C++趣味编程教材
  12. 5.信道带宽、信道容量、香农公式
  13. 电脑卡,电脑比较卡问题都出在这里，怎么解决电脑卡顿方法
  14. 数据库课设--基于Python+MySQL的餐厅点餐系统
  15. Anti-pattern
  16. 【第45期】《你好，安怡》热播，AI觉醒，奇点临近？
  17. Python将字符串转换为日期时间
  18. Java基础 switch用法
  19. error C1076: 编译器限制 : 达到内部堆限制；使用 /Zm 指定更高的限制
  20. 利用ant编译EJB(1)-生成公共包

热门文章

  1. 微信小程序后端Java接口开发与调试
  2. 你知道 FW 工程师 是做什么的吗？
  3. SPSS Modeler 数据审核学习笔记
  4. 任正非，“血洗”华为
  5. JS日期时间格式化函数
  6. win7用python哪个版本_win7自带python吗
  7. ESXI安装网卡或HBA卡驱动
  8. spring aop切面执行顺序
  9. 听完蔡学镛的分享《不瞌睡的PPT制作秘诀》后的总结
  10. 解决Tomcat中文乱码问题