程序员为什么不写文档？

Posted 2021-08-21 小魔

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

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

写作太难了

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

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

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

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

不写文档不影响开发进程

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

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

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

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

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

工欲善其事，必先利其器

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

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

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

如何撰写文档？

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

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

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

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