程序员应该写文档吗?

更新日期: 2022-07-28阅读: 1.2k标签: 文档

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

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

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

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

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

  • 架构设计文档

  • 概要设计文档

  • 详细设计文档

  • 系统部署文档

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

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

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

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

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

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

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

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

docsify - 生成文档网站简单使用教程

docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行。

DTD文档模型是什么?

DTD文档模型是DOCTYPE文档声明,是Doucument Type Definition的英文缩写,是文档类型定义;制作一个标准的页面,声明一个正确的DOCTPYE,HTML里面的标识和CSS才能正常生效.

撰写后台需求文档需要注意的那些事儿

很多产品经理在撰写后台的需求文档时会一脸懵,很多时候不知道怎么开始,这篇文章主要根据自己工作中对后台的理解和需求文档撰写经验进行分享。人员较小的公司,会要求产品经理后台管理和前台界面一起进行撰写。

docsify一个神奇的文档生成工具

在开发项目时,我们或许需要一份精致的开发文档,那么使用docsify是不错的选择,docsify是一个文档生成工具,它直接加载 Markdown 文件并动态渲染,同时还可以生成封面页。所以我们只需要写完 Markdown 文

程序员为什么不写文档?

为什么程序员不写文档?是不想写吗?最近,资深软件工程师 Kislay Verma 分析了背后的深层原因。他认为软件工程师不写文档有以下两个主要原因。

React新文档:不要滥用Ref哦~

React新文档有个很有意思的细节:useRef、useEffect这两个API的介绍,在文档中所在的章节叫Escape Hatches(逃生舱)。显然,正常航行时是不需要逃生舱的,只有在遇到危险时会用到。

为什么几乎所有技术文档读起来都非常难受?

我们学习一个新接触的文档时,常常觉得非常难受,而自己消化了再写教程就非常舒服,这会让人产生一种错觉,就是官方文档没好好写。那么实际上,官方文档为什么长期以来,难以代替第三方教程的存在呢?

内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权或违规,请与小编联系!情况属实本人将予以删除!