为什么_程序员为什么不写文档？

置顶/星标公众号????&＃xff0c;硬核文章第一时间送达&＃xff01;

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

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

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

1.写作太难了

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

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

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

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

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

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

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

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

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

总之&＃xff0c;放弃写文档太容易了。

工欲善其事&＃xff0c;必先利其器

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

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

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

如何撰写文档&＃xff1f;

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

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

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

关注公众号「高效程序员」????&＃xff0c;一起优秀&＃xff01;

回复“1024”&＃xff0c;送你一份程序员大礼包。