文檔需要全面，實(shí)時(shí)更新，并且易懂。我說(shuō)的全面是指除了介紹程序的功能外還應(yīng)該覆蓋到代碼中一些重要的地方。對(duì)很多人來(lái)說(shuō)文檔的重要性不言而喻，但很難保持它的及時(shí)性和準(zhǔn)確性。糟糕的文檔的后果通常會(huì)浪費(fèi)更多的資源和時(shí)間。往往都是出于一些錯(cuò)誤的原因而編寫(xiě)的文檔。
要求文檔的一些原因
有很多原因?qū)е挛覀冃枰帉?xiě)文檔。團(tuán)隊(duì)經(jīng)常會(huì)由于一些制度上的要求而編寫(xiě)文檔，或者就是純粹出于無(wú)知。下面是一些編寫(xiě)文檔的錯(cuò)誤的理由：
有人認(rèn)為文檔和項(xiàng)目的成敗息息相關(guān)。
文檔能夠證明某些人的存在。
需求方除了文檔也不知道要什么好
要你提供文檔的人也就是求個(gè)安心，知道事情都OK了
工作流程提示說(shuō)，你該創(chuàng)建文檔了
文檔都是過(guò)時(shí)的
軟件文檔的一個(gè)主要的問(wèn)題就是它通常都不是最新的。代碼的某個(gè)部分可能發(fā)生了改動(dòng)，但是文檔卻體現(xiàn)不出這個(gè)情況。這句話適用于幾乎所有的文檔，影響最大的其實(shí)還是需求和
測(cè)試用例。不管你多努力，文檔的過(guò)期無(wú)可避免。
文檔對(duì)誰(shuí)有用？
取決于不同的受眾，文檔的類型和格式也會(huì)相應(yīng)地有所不同。開(kāi)發(fā)人員，測(cè)試人員，客戶，主管，最終用戶都是文檔的最大的潛在用戶。
開(kāi)發(fā)人員
開(kāi)發(fā)人員不應(yīng)該依賴于文檔，因?yàn)樗鼈兺ǔ６际沁^(guò)時(shí)的。除此之外，沒(méi)有什么文檔能比代碼本身更能提供詳細(xì)以及最新的信息了。如果你想知道某個(gè)方法做了些什么，看下這個(gè)方法吧。不確定某個(gè)類是干嘛的？看一眼它。通常只有代碼寫(xiě)的太差了才需要給它添加文檔。
使用代碼本身作為文檔，這并不代表不需要其它的文檔了。關(guān)鍵是要避免冗余。如果看一下代碼就能獲取到系統(tǒng)的詳細(xì)信息，那么還可以有一些其它的文檔來(lái)提供快速導(dǎo)讀以及更高層面的一個(gè)概述的功能。代碼本身的文檔是回答不了這個(gè)系統(tǒng)是干嘛的或者這個(gè)系統(tǒng)用到了什么技術(shù)啊這種類型的問(wèn)題。大多數(shù)情況下，對(duì)于開(kāi)發(fā)人員而言，一個(gè)簡(jiǎn)單的README.md就足夠他快速入門(mén)的了。像項(xiàng)目描述，環(huán)境配置，安裝，構(gòu)建及打包指令這些東西對(duì)項(xiàng)目的新成員來(lái)說(shuō)非常有用。但那之后，代碼就是你的圣經(jīng)。產(chǎn)品代碼提供了所有需要的詳細(xì)信息，而測(cè)試代碼則是作為產(chǎn)品代碼的內(nèi)在意圖的一個(gè)描述。測(cè)試用例就是可執(zhí)行的文檔，而TDD（測(cè)試驅(qū)動(dòng)開(kāi)發(fā)）就是實(shí)現(xiàn)它的最常見(jiàn)的方式。
假設(shè)你用了某種持續(xù)集成的方式，如果測(cè)試-文檔（這里測(cè)試就是文檔，文檔也是測(cè)試）中有一部分不對(duì)了，這個(gè)用例會(huì)執(zhí)行失敗，它將會(huì)很快得到修復(fù)。持續(xù)集成解決了測(cè)試-文檔不正確的問(wèn)題，不過(guò)它不能保證所有功能都是有文檔的。由于這個(gè)原因（當(dāng)然也有其它原因）測(cè)試-文檔應(yīng)當(dāng)用TDD的方式來(lái)創(chuàng)建。如果在代碼開(kāi)發(fā)前，所有的功能都定義成測(cè)試用例，那么測(cè)試用例就能作為開(kāi)發(fā)人員的一個(gè)完備的最新的文檔了。
那團(tuán)隊(duì)的其它成員怎么辦？測(cè)試人員，客戶，主管，還有其它非碼農(nóng)呢，他們可能無(wú)法從產(chǎn)品和測(cè)試的代碼中獲取到所需要的信息。
測(cè)試人員
最常見(jiàn)的兩種測(cè)試就是
黑盒測(cè)試和
白盒測(cè)試。這個(gè)區(qū)分很重要，因?yàn)樗鼘y(cè)試人員也分成了兩類，一撥是知道怎么寫(xiě)代碼的，至少是能讀懂代碼的（白盒測(cè)試），另一撥是不懂代碼的（黑盒測(cè)試）。有的時(shí)候測(cè)試人員也兩樣都干。不過(guò)一般而言，測(cè)試都是不懂代碼的，因此對(duì)開(kāi)發(fā)人員有用的文檔對(duì)他們來(lái)說(shuō)是沒(méi)意義的。如果說(shuō)要從代碼中剝離出文檔的話，
單元測(cè)試可不是什么合適的東西。這就是BDD（行為驅(qū)動(dòng)開(kāi)發(fā)，Behavior Driven Development）存在的價(jià)值了。它能為非開(kāi)發(fā)人員提供所需的文檔，但同時(shí)還兼?zhèn)銽DD和自動(dòng)化的優(yōu)點(diǎn)。
客戶
客戶需要能夠給系統(tǒng)增加新的功能，同時(shí)他們也需要獲取到關(guān)于當(dāng)前系統(tǒng)的重要信息。給他們的文檔可不能太技術(shù)了（代碼當(dāng)然不行），同時(shí)也得是最新的。行為驅(qū)動(dòng)開(kāi)發(fā)（BDD，Behavior Driven Development）的故事和場(chǎng)景應(yīng)該是提供這類文檔的最佳方式了。它能夠作為驗(yàn)收標(biāo)準(zhǔn)（在代碼開(kāi)發(fā)前），還可以反復(fù)的執(zhí)行，同時(shí)還能用自然語(yǔ)言編寫(xiě)，這使得BDD不僅僅能夠保證文檔是最新的，同時(shí)它對(duì)那些不想看代碼的人來(lái)說(shuō)也非常有用。
可執(zhí)行的文檔
文檔是軟件不可或缺的一部分。正如軟件的其它部分一樣，它也得經(jīng)常進(jìn)行測(cè)試，這樣才能保證它是準(zhǔn)確的并且是最新的。實(shí)現(xiàn)這個(gè)最有效的方法就是將這個(gè)可執(zhí)行的文檔能夠集成到你的持續(xù)集成系統(tǒng)里面。TDD是這個(gè)方向的不二選擇。從較低層面來(lái)看的話，單元測(cè)試就非常適合作為這個(gè)文檔。另一方面來(lái)說(shuō)的話，在功能層面來(lái)說(shuō)BDD是一個(gè)很好的方式，它可以使用自然語(yǔ)言來(lái)進(jìn)行描述，這保證了文檔的可讀性。