程序員為什么不寫文檔?

置頂/星標(biāo)公眾號??，硬核文章第一時間送達(dá)！

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

為什么程序員不寫文檔？是不想寫嗎？最近，資深軟件工程師 Kislay Verma 分析了背后的深層原因。

他認(rèn)為軟件工程師不寫文檔有以下兩個主要原因。

1.寫作太難了

和所有人一樣，軟件工程師不寫文檔的原因是寫作非常難。

寫作本身是一件要求很高的任務(wù)，需要寫作者將想法清晰地組織起來，進(jìn)行批判性思考，最后再清楚表達(dá)出來。

在編程世界中，最佳答案等所有事情都基于一定程度的權(quán)衡，這也就使得寫作更加困難。程序員在寫作時需要先說明背景，證明決策的正確性，再將低級思考引入代碼。這類寫作如果做好的話往往很有用，但想做好并非易事，甚至有時候僅僅完成寫作就已經(jīng)很困難了。糟糕的代碼還能運行，但糟糕的文檔不會。

這就是許多人針對代碼注釋的價值和自文檔化代碼（self-documenting code）展開爭論的原因?！冻绦騿T應(yīng)該知道的 97 件事》的作者 Kevlin Henney 曾說，為復(fù)雜代碼添加注釋是徒勞的，用代碼里都無法表達(dá)清楚，怎么可能用文字表達(dá)清楚呢？

2.不寫文檔不影響開發(fā)進(jìn)程

開發(fā)者不寫文檔，并不耽誤工作進(jìn)程，起碼不會立刻帶來什么負(fù)面影響。而事實上，不將技術(shù)決策文檔化帶來的影響是一直在累積的。

寫作是一件關(guān)乎思考和分析的事。大多數(shù)情況下，寫代碼可以摸著石頭過河。組織結(jié)構(gòu)欠佳的代碼或許也能運行，但胡亂堆砌的文字和段落很難讓人讀懂。寫作必須清晰，才能有用。而代碼只要能夠運行就可以（一定程度上）被接受。由于大部分組織只關(guān)注如何使產(chǎn)品推進(jìn)，于是那些不會影響開發(fā)進(jìn)程的事情就理所當(dāng)然被忽略了。

在很多團(tuán)隊中，單元測試也面臨類似的問題。要想測試代碼，我們需要首先理解它，但這要比寫代碼費工夫多了，而且不做單元測試也不影響工作進(jìn)程。于是，很多團(tuán)隊不重視對代碼做單元測試。

還有一個問題：過時。即使優(yōu)秀的文檔也會過時，因此工程師在構(gòu)建系統(tǒng)時，必須不斷地重復(fù)「思考 - 分析 - 表達(dá)」這一過程。

總之，放棄寫文檔太容易了。

工欲善其事，必先利其器

毫無疑問，目前用于文檔撰寫的工具并不足夠。我們并不以文檔的角度思考問題，而是從 idea 和目標(biāo)的角度考慮，一次性拼湊好幾個概念。文檔是思考過程的反映，這樣形成的文檔質(zhì)量就可想而知了。我們需要一些工具，幫助我們梳理不同時間的想法，進(jìn)而解決手邊的問題。對于這類寫作而言，Google Docs、Confluence、Markdown 并不足夠。

不過，新一代工具（如 Notion、Roam）正在解決「網(wǎng)絡(luò)化思想」的問題。這些工具有助于將思考轉(zhuǎn)化為文檔。

但是，缺少工具絕非不寫作的借口。工具當(dāng)然有用，但是否具備寫作意愿才是問題的關(guān)鍵。

如何撰寫文檔？

Kislay Verma 表示：「寫軟件教會了我一件事。想要用戶做某件事，你必須使這件事成為使用產(chǎn)品過程中必不可少的一步?！箤懽饕彩侨绱?。將文檔作為代碼的點綴不會奏效，甚至是無用的。

寫作關(guān)乎批判性思考，需要你向自己和讀者解釋思考過程和意圖。思考過程為文檔 / 寫作增加了價值，而不只是靜態(tài)地記錄已經(jīng)實現(xiàn)的代碼。

Mob 編程 / 成對編程和極限編程的支持者通?？摧p文檔寫作。但除了那些類型之外，寫作和 review 技術(shù)文檔是團(tuán)隊共同理解自己所創(chuàng)建產(chǎn)品的唯一方式，這對團(tuán)隊和代碼庫的長期健康發(fā)展非常關(guān)鍵。

關(guān)注公眾號「高效程序員」??，一起優(yōu)秀！