头图

程序员为什么不写文档?

小魔
English

为什么程序员不写文档?是不想写吗?最近,资深软件工程师 Kislay Verma 分析了背后的深层原因。

他认为软件工程师不写文档有以下两个主要原因。

写作太难了

和所有人一样,软件工程师不写文档的原因是写作非常难。

写作本身是一件要求很高的任务,需要写作者将想法清晰地组织起来,进行批判性思考,最后再清楚表达出来。

在编程世界中,最佳答案等所有事情都基于一定程度的权衡,这也就使得写作更加困难。程序员在写作时需要先说明背景,证明决策的正确性,再将低级思考引入代码。这类写作如果做好的话往往很有用,但想做好并非易事,甚至有时候仅仅完成写作就已经很困难了。糟糕的代码还能运行,但糟糕的文档不会。

这就是许多人针对代码注释的价值和自文档化代码(self-documenting code)展开争论的原因。《程序员应该知道的 97 件事》的作者 Kevlin Henney 曾说,为复杂代码添加注释是徒劳的,用代码里都无法表达清楚,怎么可能用文字表达清楚呢?

不写文档不影响开发进程

开发者不写文档,并不耽误工作进程,起码不会立刻带来什么负面影响。而事实上,不将技术决策文档化带来的影响是一直在累积的。

写作是一件关乎思考和分析的事。大多数情况下,写代码可以摸着石头过河。组织结构欠佳的代码或许也能运行,但胡乱堆砌的文字和段落很难让人读懂。写作必须清晰,才能有用。而代码只要能够运行就可以(一定程度上)被接受。由于大部分组织只关注如何使产品推进,于是那些不会影响开发进程的事情就理所当然被忽略了。

在很多团队中,单元测试也面临类似的问题。要想测试代码,我们需要首先理解它,但这要比写代码费工夫多了,而且不做单元测试也不影响工作进程。于是,很多团队不重视对代码做单元测试。

还有一个问题:过时。即使优秀的文档也会过时,因此工程师在构建系统时,必须不断地重复「思考 - 分析 - 表达」这一过程。

总之,放弃写文档太容易了。

工欲善其事,必先利其器

毫无疑问,目前用于文档撰写的工具并不足够。我们并不以文档的角度思考问题,而是从 idea 和目标的角度考虑,一次性拼凑好几个概念。文档是思考过程的反映,这样形成的文档质量就可想而知了。我们需要一些工具,帮助我们梳理不同时间的想法,进而解决手边的问题。对于这类写作而言,Google Docs、Confluence、Markdown 并不足够。

不过,新一代工具(如 Notion、Roam)正在解决「网络化思想」的问题。这些工具有助于将思考转化为文档。

但是,缺少工具绝非不写作的借口。工具当然有用,但是否具备写作意愿才是问题的关键。

如何撰写文档?

Kislay Verma 表示:「写软件教会了我一件事。想要用户做某件事,你必须使这件事成为使用产品过程中必不可少的一步。」写作也是如此。将文档作为代码的点缀不会奏效,甚至是无用的。

写作关乎批判性思考,需要你向自己和读者解释思考过程和意图。思考过程为文档 / 写作增加了价值,而不只是静态地记录已经实现的代码。

Mob 编程 / 成对编程和极限编程的支持者通常看轻文档写作。但除了那些类型之外,写作和 review 技术文档是团队共同理解自己所创建产品的唯一方式,这对团队和代码库的长期健康发展非常关键。

原文链接:https://kislayverma.com/progr...

阅读 1.9k

SegmentFault 行业快讯
第一时间为开发者提供行业相关的实时热点资讯
avatar
小魔
SegmentFault 技术编辑

luxue@sifou.com

96 声望
5 粉丝
0 条评论
你知道吗?

avatar
小魔
SegmentFault 技术编辑

luxue@sifou.com

96 声望
5 粉丝
宣传栏