點(diǎn)擊上方[全棧開(kāi)發(fā)者社區(qū)]→右上角[...]→[設(shè)為星標(biāo)?]
點(diǎn)擊領(lǐng)取全棧資料：全棧資料

以下為譯文：

有人認(rèn)為程序員不喜歡寫(xiě)文檔，是因?yàn)闆](méi)有太好的工具，但是我認(rèn)為軟件工程師不喜歡不編寫(xiě)文檔有兩個(gè)主要原因：第一，寫(xiě)作很難；第二，沒(méi)有文檔代碼也可以照常發(fā)布。而工具只是微不足道的原因之一。

寫(xiě)作很難

寫(xiě)作從來(lái)都不是一件易事。軟件工程師與其他人一樣，他們不愿意寫(xiě)文檔，是因?yàn)橄胍獙?xiě)得條理清晰、簡(jiǎn)潔明了，實(shí)在是太難了。

寫(xiě)作是一項(xiàng)非常艱巨的任務(wù)。我們必須清楚地組織自己的思想，然后經(jīng)過(guò)檢查和整理，最后再清楚地表達(dá)出來(lái)。盡管最后的表達(dá)部分可以從某種程度上進(jìn)行簡(jiǎn)化（取決于寫(xiě)作的質(zhì)量），但是正確完成這三個(gè)步驟需要付出大量努力。

在編程的世界中，面對(duì)所有問(wèn)題，我們能夠給出的最佳答案都是：“視具體情況而定”，一切都需要權(quán)衡取舍，但寫(xiě)作則更加復(fù)雜。你需要預(yù)設(shè)上下文，證明決策的合理性，然后論證代碼底層思想的推動(dòng)力。這樣的文檔只有編寫(xiě)得好才會(huì)有用，但寫(xiě)好太難了，所以往往根本做不到。錯(cuò)誤的代碼仍然可以運(yùn)行，但錯(cuò)誤的文檔則不會(huì)。 

這就是為什么很多人都在爭(zhēng)論在代碼中添加注釋的價(jià)值，以及能作為文檔使用的代碼的優(yōu)點(diǎn)。Kevlin Henney認(rèn)為，在復(fù)雜的代碼周?chē)砑幼⑨寣?shí)際上是徒勞的，如果開(kāi)發(fā)人員無(wú)法通過(guò)代碼清楚地表達(dá)自己，你又怎么期望他能用英語(yǔ)清楚地表達(dá)自己呢？

沒(méi)有文檔代碼也可以照常發(fā)布

即便開(kāi)發(fā)人員不編寫(xiě)文檔，他們?nèi)匀豢梢酝瓿勺约旱墓ぷ?。沒(méi)有文檔也不會(huì)阻礙交付代碼（至少不會(huì)馬上有問(wèn)題）。沒(méi)有文檔記錄的技術(shù)決策所造成的損害是累積性的。就像技術(shù)負(fù)債一樣，不會(huì)立即造成傷害。

就像我上面所說(shuō)，寫(xiě)作主要是思考和分析問(wèn)題。大多數(shù)時(shí)候，編程只需要憑借自己的經(jīng)驗(yàn)和判斷。一堆雜亂無(wú)章的代碼照樣可以運(yùn)行，但是一堆亂七八糟的單詞和段落則無(wú)法形成文章。寫(xiě)作必須清晰才能發(fā)揮作用。只要代碼能夠完成工作，就可以被接受（在某種程度上）。而且，由于大多數(shù)組織只在乎產(chǎn)品的交付，因此凡是不會(huì)阻礙產(chǎn)品交付的工作都會(huì)被忽略。

在許多團(tuán)隊(duì)中，單元測(cè)試也面臨著類似的問(wèn)題。為了測(cè)試代碼，我們首先需要理解代碼（而且往往花費(fèi)的時(shí)間超過(guò)了編寫(xiě)代碼），而且沒(méi)有測(cè)試也不會(huì)阻礙產(chǎn)品的交付。因此，太好了，代碼中沒(méi)有單元測(cè)試。

還有過(guò)時(shí)的問(wèn)題。即便是精心編纂的文檔也會(huì)過(guò)時(shí)，因此工程師在構(gòu)建系統(tǒng)時(shí)，必須不斷重復(fù)思考-分析-表達(dá)的過(guò)程。因此，我們很容易拋棄文檔這項(xiàng)重任。因此，我們往往會(huì)臨時(shí)抱佛腳，等到必要時(shí)再編寫(xiě)和整理文檔。

工具

毫無(wú)疑問(wèn)，如今能夠幫助我們編寫(xiě)軟件文檔的常用工具嚴(yán)重不足。我們不會(huì)一次只考慮一個(gè)文檔，而是會(huì)將多個(gè)概念匯總起來(lái)，思考多個(gè)想法和目標(biāo)。最終的文檔只是整個(gè)思想過(guò)程的一種體現(xiàn)。我們需要工具幫助我們整理思路，以解決眼前的問(wèn)題。Google Docs、Confluence和Markdown都是此類的寫(xiě)作工具，但都不怎么好用。

雖然工具有一定的影響，但不愿意承擔(dān)這項(xiàng)任務(wù)才是真正的問(wèn)題所在。

文檔該怎么辦？

編寫(xiě)軟件教會(huì)了我一件事。如果你希望用戶做某件事情，那么就必須讓它變成他們?cè)谑褂卯a(chǎn)品的過(guò)程中非做不可的事情。同樣，如果文檔只是代碼的附屬品，那么永遠(yuǎn)不會(huì)有人主動(dòng)編寫(xiě)文檔。更糟糕的是，文檔還沒(méi)有太大用處。寫(xiě)作需要批判性思維。文檔的目的是向自己和聽(tīng)眾（比如你的團(tuán)隊(duì)）解釋你的思維過(guò)程和意圖。而這個(gè)思維過(guò)程才是文檔提供的價(jià)值，而不是編寫(xiě)好的靜態(tài)文字。

支持結(jié)對(duì)編程的人經(jīng)常貶低文檔。但是，編寫(xiě)和審核技術(shù)文檔是團(tuán)隊(duì)對(duì)他們構(gòu)建的產(chǎn)品形成統(tǒng)一認(rèn)識(shí)的唯一渠道。這種統(tǒng)一的認(rèn)識(shí)對(duì)于團(tuán)隊(duì)和代碼庫(kù)的長(zhǎng)期健康至關(guān)重要。

我認(rèn)為，想要讓文檔的編寫(xiě)長(zhǎng)期堅(jiān)持下去，唯一的辦法就是讓其成為軟件開(kāi)發(fā)的阻礙。編寫(xiě)文檔應(yīng)該成為流程的一部分。根據(jù)我的經(jīng)驗(yàn)，下面這些方法或許能起到作用。

• 在編寫(xiě)代碼之前，首先編寫(xiě)文檔。除非代碼改動(dòng)非常小，否則每位工程師都應(yīng)該寫(xiě)一份注釋，說(shuō)明他們將要進(jìn)行的工作，并由團(tuán)隊(duì)的其他成員來(lái)實(shí)際執(zhí)行。經(jīng)過(guò)詳盡的討論后，實(shí)際的代碼改動(dòng)就微不足道了。

• 簡(jiǎn)化文檔的編寫(xiě)工作。不要將文檔的編寫(xiě)弄得過(guò)于復(fù)雜。圖表等花里胡哨的東西可以先放一放。你只需要簡(jiǎn)單地寫(xiě)下你的想法、所做的事情以及原因。即使文檔只能為現(xiàn)在和將來(lái)的團(tuán)隊(duì)其他成員提供基本的說(shuō)明，也非常有價(jià)值。

• 記錄下備選方案。無(wú)需詳細(xì)記錄實(shí)際的實(shí)現(xiàn)（因?yàn)閷?shí)現(xiàn)可能隨時(shí)間而變化），你應(yīng)該重點(diǎn)記錄選擇某個(gè)方案的原因。這是代碼無(wú)法解釋的內(nèi)容，因此記錄下來(lái)很有價(jià)值。你可以根據(jù)實(shí)際情況，投入一定的時(shí)間來(lái)記錄詳細(xì)信息。

• 便于查找。如果人們找不到文檔，那么就沒(méi)有任何用途。你可以使用支持文本搜索的工具。

• 記錄變更。有些組織使用版本控制來(lái)記錄系統(tǒng)設(shè)計(jì)隨時(shí)間推移發(fā)生的變更。如果你沒(méi)有類似的工具，那么請(qǐng)針對(duì)每個(gè)功能保留一份文檔，并在其上不斷添加最新的更新信息，以便記錄下所有的變更。

最后，希望團(tuán)隊(duì)能夠在建立文檔和查看文檔的過(guò)程中，逐步認(rèn)識(shí)到文檔帶來(lái)的價(jià)值，并養(yǎng)成記錄文檔的好習(xí)慣。但在此之前，你應(yīng)該將編寫(xiě)文檔視為減肥或節(jié)食，痛苦而快樂(lè)地堅(jiān)持下去。

原文鏈接：https://kislayverma.com/programming/why-programmers-dont-write-documentation/

轉(zhuǎn)載：CSDN