軟件開發實踐:如何將編碼和文檔相結合

好像軟件開發人員都特別討厭文檔（我的觀察，我的觀點）。作軟件有一大堆文檔，例如項目立項報告，需求調研報告，需求規格說明書，概要設計報告，詳細設計報告...。文檔一大堆，真正讓你們仔細閱讀，起到做用的好像很少。

倒也不是這些文檔沒有，其實這些文檔的做者都是費很大的心力去完成的，雖然有些段落是文檔中模板須要才添加的，有不少套話。可是仍是有不少章節是頗有用，做者下了很大功夫的， 對開發頗有用的。如項目立項報告中對開該項目的定位，市場分析及可能造成的門檻和競爭優點的分析都是頗有用的。需求調研報告中的競品分析，特性識別也是頗有用的。需求規格說明書也是開發人員在開發過程當中，會時不時找出來仔細閱讀，認真去摳的。

可是文檔給咱們的感受仍是雖然下了大力氣寫，可是好像效果都很差，性價比不高。

在敏捷開發中， 對文檔就不是很重視了。在敏捷開發中， 提倡講述用戶故事，而後就是實現，測試等。敏捷開發提倡源代碼即文檔。

當時在作了多年的開發後，我發覺適當的文檔，對於產品經理，開發者，測試人員之間的溝通，仍是頗有用的。

最近進行了一次編碼和文檔相結合的實現，在這裏寫出來，和你們交流一下。

1 概述

最近作了一個小功能。代碼作完後大約有800-1000行左右（C程序），功能比較獨立， 並且是有一個後臺需求， 沒有UI。我嘗試在開發這個功能的過程當中寫文檔。

這個文檔是按照本身的理解寫的， 沒有套用任何模板。最開始也是本身使用的，做爲整理思路的工具。該文檔後來也用於與產品經理及測試人員溝通。本身以爲效果還能夠。經過該文檔，與產品經理澄清了一些本身認識不正確的地方。 該文檔給測試人員提供了幫助，並且能讓測試人員儘可能的瞭解了需求和設計。

2文檔內容

2.1需求整理

首先是關於需求的整理。由於只有理解好需求才能開發出正確的軟件。怎麼算是理解了需求， 寫出來，並於需求相關人員達成一致，才能算理解了需求。

之前常常會遇到開發人員本身覺得理解了需求， 下手開發，開發完成後才發現和需求人員理解的不一致， 甚至需求人員理解與客戶的真正需求不一致的狀況。因此上來我就對需求進行整理。

到這兒，可能你們會頭大。用瀑布式開發流程下，寫過需求調研報告和需求規格說明書的人知道，這些都是大工程，工做量大，並且預期效果也很差。

在這裏，我沒有按照之前的需求規格說明書的思路整理需求。而是採用敏捷開發中的用戶故事的方式來寫。

2.1.1用戶需求

用戶需求按照以下樣式寫的：

做爲一名...，我但願...， 以便於...。

這裏沒有之前需求規格說明書中大寫繁瑣的部分，只是簡單的一句話，當時頗有用。若是你沒有寫過，很是建議你試試。

該段文字信息量仍是比較大， 並且每一段都是很重要的，根據優先級有大到小：以便於>做爲一名>我但願。

關於這句話，簡易看看《軟件需求 第三版》的相關章節，寫的很好。《敏捷革命》的第六章中的「不要盲目執行任務， 要領會用戶故事」對這個句子也有精彩的描述。

關於這部分，個人建議是：

不要超過5條，若是超過條，請仔細反思一下，是否是對需求真正理解了。（個人前提是一個較小的功能）。

關於這部分，在個人實踐中， 最開始以兩條（實際用戶和維護人員）， 後來又一次識別出了一條（工廠模式的測試人員）。

2.1.2功能需求

有了用戶需求後， 須要將用戶需求細化爲功能需求，也就是功能點。簡易用下面的語句：

A應該...。

我本次的實踐中，功能點共6項， 包括「該功能應該提供完善的日誌，以便於在出現爲你的時候，經過日誌能快速定位問題」和「在系統重啓後，日誌不該該丟失」等。其中多數是在開始時識別出來的，也有後來添加的，例如工廠模式下的特殊處理。

2.1.3限制，依賴和假設

在咱們的功能開發中，實際上是有不少限制，依賴和假設的。不少時候，咱們會把這些依賴和限制記在內心，這是不夠的，咱們須要把它們寫出來。這些對咱們開發人員，測試人員和需求相關人員都頗有用。這些限制，依賴和假設要獲得需求人員的承認，測試人員的理解。在編碼時候，咱們甚至須要把這些做爲註釋放在代碼中。

2.1.4總結

關於需求的整理，須要獲得需求人員和客戶的承認，開發人員保證真正的理解（個人理解： 在用戶需求中，能真正明白「以便於」部分和「做爲一名」部分，就算是真正瞭解了）， 測試人員應該深刻了解這些內容，才能知道功能的前因後果，寫出正確的測試用例。

在個人實踐中，這部分的文檔其實很少， 應該只有半頁多一點的文檔。

 

2.2需求測試用例

根據需求編寫需求測試用例，我是站在開發者的角度寫的測試用例，目標就是覆蓋需求中的功能點及其各類狀況。格式比較隨意， 主要是能把這些功能都驗證了，沒有落下測試點。

在本次實踐中，我共編寫10條測試用例。

這些測試用例但願能獲得測試人員的評審。

其實測試人員未必會直接用這些測試用例，可是能給他們很大的輔助。本次實踐中， 測試人員對這些測試用例仍是很關注的。

2.3設計

主要是記錄下設計中的想法和思路。在本次實踐中， 我畫了一張關聯圖，主要用來標識該功能中， 系統與哪些外部對象交互，交互了哪些信息。而後用一些文字表述了實現的基本思路。

本次實踐中，設計部分大約佔半頁， 包括關聯圖。

2.4 設計測試用例

針對設計設計的測試用例。這一塊也須要測試人員評審。 可是這塊測試主要是我本身使用的。由於我以爲一個功能發佈出去，最好本身能作以便FT測試。

本次事件中，設計的測試用例大約有*項。

2.5實現

這一部分主要是給代碼Review的人看的。由於我以爲讓別人給本身Review代碼，只提供一個ReviewBoard或diff文件，不是很好。

在本次實踐中，我提供了一個時序圖，並在發出Review請求的時候，將該文檔做爲附件也發送了出去。

若是是用面向對象編程，我可能會提供一個類圖及一個類列表，在類圖中表述類之間的關係，在類列表中，描述一個每一個類的功能及想法。

3總結

以上是本身本次實踐中的文檔。我的以爲對本身的開發頗有幫助，並且文檔的規模也不大，維護成本也不高。

該文檔將客戶和需求人員，開發人員，測試人員以及代碼Review人員都涉及到了。

此次實踐實際上是我看了《軟件需求 第三版》後的一次練習（項目是個正式的項目）。

最開始是從需求部分開發的。

雖然已經有需求人員整理了需求，可是沒有表達爲文字。鑑於之前常常出現開發人員對需求的理解與實際不一致的狀況，我就對需求按照《軟件需求 第三版》說的作了整理（筆者有十多年編寫需求規格說明書的經驗，可是總以爲之前在瀑布發下寫的需求規格說明書並很差，主要困惑容易在需求規格說明書中包含過多設計），而且發給相關人員看。

獲得承認後， 又以爲既然功能明確了，能夠嘗試讓本身站在一個測試者的角度看，該怎麼測試， 因而有了需求測試用例相關部分。

由於到這時候，文檔仍是很小，因此我就把設計及設計的測試用例都放在一塊兒了，做爲本身使用的文檔。

在編碼完成後，考慮到方便別人Review，又把時序圖加了上來。

這就是我本次的文檔實踐。