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