程序員爲何不寫文檔？

爲何程序員不寫文檔？是不想寫嗎？最近，資深軟件工程師 Kislay Verma 分析了背後的深層緣由。

他認爲軟件工程師不寫文檔有如下兩個主要緣由。

寫做太難了

和全部人同樣，軟件工程師不寫文檔的緣由是寫做很是難。

寫做自己是一件要求很高的任務，須要寫做者將想法清晰地組織起來，進行批判性思考，最後再清楚表達出來。

在編程世界中，最佳答案等全部事情都基於必定程度的權衡，這也就使得寫做更加困難。程序員在寫做時須要先說明背景，證實決策的正確性，再將低級思考引入代碼。這類寫做若是作好的話每每頗有用，但想作好並不是易事，甚至有時候僅僅完成寫做就已經很困難了。糟糕的代碼還能運行，但糟糕的文檔不會。

這就是許多人針對代碼註釋的價值和自文檔化代碼（self-documenting code）展開爭論的緣由。《程序員應該知道的 97 件事》的做者 Kevlin Henney 曾說，爲複雜代碼添加註釋是徒勞的，用代碼裏都沒法表達清楚，怎麼可能用文字表達清楚呢？

不寫文檔不影響開發進程

開發者不寫文檔，並不耽誤工做進程，起碼不會馬上帶來什麼負面影響。而事實上，不將技術決策文檔化帶來的影響是一直在累積的。

寫做是一件關乎思考和分析的事。大多數狀況下，寫代碼能夠摸着石頭過河。組織結構欠佳的代碼或許也能運行，但胡亂堆砌的文字和段落很難讓人讀懂。寫做必須清晰，纔能有用。而代碼只要可以運行就能夠（必定程度上）被接受。因爲大部分組織只關注如何使產品推動，因而那些不會影響開發進程的事情就理所固然被忽略了。

在不少團隊中，單元測試也面臨相似的問題。要想測試代碼，咱們須要首先理解它，但這要比寫代碼費工夫多了，並且不作單元測試也不影響工做進程。因而，不少團隊不重視對代碼作單元測試。

還有一個問題：過期。即便優秀的文檔也會過期，所以工程師在構建系統時，必須不斷地重複「思考 - 分析 - 表達」這一過程。

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

工欲善其事，必先利其器

毫無疑問，目前用於文檔撰寫的工具並不足夠。咱們並不以文檔的角度思考問題，而是從 idea 和目標的角度考慮，一次性拼湊好幾個概念。文檔是思考過程的反映，這樣造成的文檔質量就可想而知了。咱們須要一些工具，幫助咱們梳理不一樣時間的想法，進而解決手邊的問題。對於這類寫做而言，Google Docs、Confluence、Markdown 並不足夠。

不過，新一代工具（如 Notion、Roam）正在解決「網絡化思想」的問題。這些工具備助於將思考轉化爲文檔。

可是，缺乏工具絕非不寫做的藉口。工具固然有用，可是否具有寫做意願纔是問題的關鍵。

如何撰寫文檔？

Kislay Verma 表示：「寫軟件教會了我一件事。想要用戶作某件事，你必須使這件事成爲使用產品過程當中必不可少的一步。」寫做也是如此。將文檔做爲代碼的點綴不會奏效，甚至是無用的。

寫做關乎批判性思考，須要你向本身和讀者解釋思考過程和意圖。思考過程爲文檔 / 寫做增長了價值，而不僅是靜態地記錄已經實現的代碼。

Mob 編程 / 成對編程和極限編程的支持者一般看輕文檔寫做。但除了那些類型以外，寫做和 review 技術文檔是團隊共同理解本身所建立產品的惟一方式，這對團隊和代碼庫的長期健康發展很是關鍵。

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