程序员为什么不写文档？

朱雀 2022-10-10 11:17 166阅读 0赞

![4573a1c5b2776a89341ca16bd12d83a9.gif][]

置顶/星标公众号????，硬核文章第一时间送达！

链接 | https://kislayverma.com/programming/why-programmers-dont-write-documentation/em

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

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

#### **1.写作太难了** ####

--------------------

####     ####

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

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

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

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

#### **2.不写文档不影响开发进程** ####

--------------------

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

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

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

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

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

#### **工欲善其事，必先利其器** ####

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

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

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

#### **如何撰写文档？** ####

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

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

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

**关注****公众****号****「高效程序员」**????，一起优秀！

回复“1024”，送你一份程序员大礼包。

[4573a1c5b2776a89341ca16bd12d83a9.gif]: /images/20221005/03ad7af796474cadae18c63cf744a8e1.png

发表评论取消回复

表情：

评论列表（有 0 条评论，166人围观）

还没有评论，来说两句吧...

相关阅读

相关程序员为什么不喜欢关电脑？

程序员为什么不喜欢关电脑？

一时失言乱红尘/ 2024年04月24日 14:51/ 0 赞/ 69 阅读

相关为什么要写文档

写文档的原因有很多。 1. 记录信息: 文档可以帮助记录重要的信息和细节, 包括项目进度、设计决策、代码实现等。 2. 沟通协作: 文档可以帮助团队成员之间进行沟通和协作

朴灿烈づ我的快乐病毒、/ 2024年03月26日 09:18/ 0 赞/ 63 阅读

相关 php不会写,为什么小弟我不会写代码

为什么我不会写代码？ if($\_GET\['do'\]=='add')\{ include DedeInclude('templets/student/student\_

桃扇骨/ 2023年01月17日 10:53/ 0 赞/ 167 阅读

相关程序员为什么要写博客

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ub

￡神魔★判官ぃ/ 2023年01月11日 09:09/ 0 赞/ 248 阅读

相关为什么程序员不需要MATLAB技能？

背景：汇总了下老王在其他平台的原创回复，欢迎关注老王原创公众号【软件老王】，关注不迷路。 -------------------- 1、为什么招程序员不考虑MATLA

女爷i/ 2022年12月19日 08:53/ 0 赞/ 162 阅读

相关程序员为什么不写文档？

![4573a1c5b2776a89341ca16bd12d83a9.gif][] 置顶/星标公众号????，硬核文章第一时间送达！链接 | https://kislay

朱雀/ 2022年10月10日 11:17/ 0 赞/ 167 阅读

相关为什么程序员下班从来不关电脑？

转自：SegmentFault 思否技术圈先问下：你下班是不是关上显示器，戴上耳机，手机一拿，就走了？电脑：关了，但没完全关 ![1fd599edc20b2fca0b

港控/mmm°/ 2022年09月16日 06:13/ 0 赞/ 191 阅读

相关管理类软件开发为什么不给程序员开高薪？为什么？为什么？为什么？为什么？为什么？...

[为什么80%的码农都做不了架构师？>>> ][80_] ![hot3.png][] 大家千万别搞错，我说的是程序员，没有说IT人才，IT人才是值钱的，不是所有的程序

朴灿烈づ我的快乐病毒、/ 2022年01月17日 10:39/ 0 赞/ 254 阅读

相关为什么我们不要.net程序员（转）

　　也许你已经知道了，我们[正在招聘][Link 1]最优秀的程序员。不错，每个人都这样说。但是我们的程序员能打败你们的——任何时候。比如，米奇虽然只有5英尺高，但他是一个有相

电玩女神/ 2021年12月14日 10:29/ 0 赞/ 308 阅读

相关程序员为什么要写博客？怎么写博客？

> 今天就来和大家聊聊关于写博客的一些事情，首先声明哦，这都是我自己写博客那么久以来的一些想法，可能有些地方不够成熟，但我还是想着分享出来，万一对你有些帮助呢？为什么这里要

以你之姓@/ 2021年08月29日 13:01/ 0 赞/ 556 阅读