IT数码门户网,专业数码、网络、seo硬软件知识资讯网

当前位置:IT门户网 > IT资讯 > 业界 >

为什么大多数人都不喜欢写代码文档

时间:2021-09-14    来源:IT资讯    人气:

本文大部分内容翻译总结自《Software Engineering at Google》 第10章节 Documentation。另外,该书电子版近日已经可以免费下载了 https://abseil.io/resources/swe_at_google.2.pdf,有兴趣的同学可以下载翻阅下。首先声明,本问所说的文档不仅限于纯文本文档,还包含代码注释(注释也是一种特殊形式的文档)。

很多技术人自己非常轻视技术文档的书写,然而又时常抱怨文档不完善、质量差、更新不及时…… 这种在程序猿间普遍存在的矛盾甚至已经演变成了一个段子。

文档的重要性

高质量的文档对于一个组织或团队来说有非常多的益处,比如让代码和API更容易理解、错误更少;让团队成员更专注于目标;也可以让一些手工操作更容易;另外如果有新成员加入的话有文档也会让他们更快融入……

写文档有比较严重的收益滞后性,不像测试,你跑一个测试case,它能立即告诉你是对还是错,它的价值马上就体现出来了。而写一份文档,随着时间的推移,它的价值才会逐渐体现出来。你可能只写一次文档,将来它会被阅读上百次、上千次,因为一份好的文档可以在未来替你向别人回答类似下面这些问题。

为什么当时是这么决策的?

为什么代码是这样实现的?

这个项目里都有哪些概念?

……

写文档同样对于写作者也有非常大的收益:

帮你构思规范化API: 写文档的过程也是你审视你API的过程,写文档时会让你思考你API设计是否合理,考虑是否周全。如果你没法用语言将API描述出来,那么说明你当前的API设计是不合理的。

文档也是代码的另一种展现: 比如你两年后回过头来看你写过的代码,如果有注释和文档,你可以很快速理解代码。

让你的代码看起来更专业: 我们都有个感觉,只要文档齐全的API都是设计良好的API,虽然这个感觉并不完全正确,但这两者确实是强相关的,所以在很多人眼里,文档的完善度也成为衡量一个产品专业度的指标。

避免被重复的问题打扰: 有些问题你只需要写在文档里,这样有人来问你的时候你就可以让他直接去看文档了,而不是又给他解释一遍。

为什么大多数人都不喜欢写文档?

关于文档的重要性,每个技术人或多或少都知道一些,但很多人还是没有写文档的习惯,为什么?除了上文中提到的文档的收益滞后性外,还有以下几点原因:

很多工程师习惯将写代码和写作割裂开,不仅仅是在工作上,而且在思想上就认为它们是完全不相关的两项工作,这就导致好多人重代码不重文档。

也有很多工程师认为自己不善写作,索性就不写了。这实际是个偷懒的借口,写文档不需要华丽的辞藻、生动的语言,你只需要将问题讲清楚即可。

有时候工具不好用也会影响的文档写作。如果没有一个很好的写作工具将写文档嵌入到开发工作流程中的话,写作确实会增加工作的负担。

大多数人将写文档看做是工作的额外负担。我代码都没时间写,哪有时间写文档!,这其实是错误的观念,文档虽然前期有投入,但能让你代码的后期维护成本大幅降低,磨刀不误砍柴工这个道理相信大家都还是能理解的。

如何产出高质量文档

既然理解了好文档的重要性,我们如何保证在时间的长河中维护好一份文档,这里有些相关的方法论,大家可以参考下。

像管理代码一样管理文档

对于如何写出好代码,整个技术圈已经有好多经验的总结了,比如书籍《重构》《代码简洁之道》…… 针对各种编程语言,也有相关的规范,比如国外的Google C++++规范,国内的阿里Java开发规范等…… 但对于文档 似乎相关的资料却很少。但实际上,不应该把文档和代码割裂开来,你可以简单粗暴地认为文档其实就是用一种特殊语言书写的代码,这种语言就是人类的语言。这么想的话,实际上我们很多在代码和工程中总结出来的经验,也可以直接用在文档中,比如:

有统一的规范

有版本控制

有明确的责任人维护

有变更Review机制

有问题的反馈和更新机制

定期更新

有衡量的指标(比如准确性,时效性)

明确你的读者是谁

写文档有一个很常见的错误,那就是很多人文档都是写给自己看的,这种情况下就会导致你的文档只有自己或者和你有相似知识背景的人才能看懂,团队较小时这种问题还好,你们都做着类似的工作,所以也都能看懂文档。但当团队逐渐壮大后,问题就会凸显出来,新人有时候有着和你不同的工作背景,甚至现在都做着不同的工作内容,这时候你之前写的文档他们就很难读懂了。

相关文章

  • 云脉文档识别怎样将照片转换成WORD?

    云脉文档识别怎样将照片转换成WORD?

    云脉文档识别是全球最火的一款将图片智能识别转化为文字的软件,那么大家知道如何将图片内容转化为word文档吗?...
    2021-07-08 01.07.10
  • 新Android开源项目代码搜索工具发布

    新Android开源项目代码搜索工具发布

    日前有外媒报道称,Android开源代码工程主管Jeff Bailey等人共同宣布,全新的Android开源项目(AOSP)代码搜索工具已正式...
    2021-07-07 11.07.46
  • 345好压怎么进行文件压缩?

    345好压怎么进行文件压缩?

    在一些我们发送文档的时候需要将文档压缩后才能发送,那么345好压相信是一款不错的选择,345好压是一款纯免费的...
    2021-07-06 05.07.07
  • PDF可以插入文本吗?

    PDF可以插入文本吗?

    随着电脑的普及,文档的使用越来越广泛,也衍生出很多文件格式,其中最让人头疼的就是PDF了吧,大家知道PDF格式...
    2021-07-05 11.07.48
  • 小米10系列内核代码已开源

    小米10系列内核代码已开源

    小米科技日前以线上直播发布会的形式发布了两款新机,它们分别是小米10、小米10 Pro。而据最新消息显示,小米已经...
    2021-07-04 12.07.26

业界排行榜

更多>>

网络知识排行榜

更多>>

系统教程排行榜

更多>>