從零開始編寫本身的C#框架（4）——文檔編寫說明

　　在寫本系列的過程當中，瞭解得越多越不知道從哪裏作爲切入點來寫，幾乎每一個知識點展開來講均可以寫成一本書。而本身在寫做與文檔編寫方面來講，仍是一個初鳥級別，因此只能從大方面說說，在本框架開發所需的範圍內來說述相關要用到的知識點，至於要更深刻的去了解，請你們觀看其餘大牛的博客或購買書籍來學習。

　　爲了加快進度，會對目錄進行修改，將一些知識點合併或在後面使用的章節再進行描述。

　　謝謝你們的支持，若是您以爲本文對您有所幫助，請幫忙點擊支持或發表評論。

 

　　在開發的過程當中，要編寫各類各樣的文檔，固然也有很多公司根本就沒有文檔。對於初學者，包括至關多有多年開發經驗的人，提及編寫文檔都會很是抗拒，一講到寫文檔不少人都是一個頭兩個大，不知道怎麼編寫也懶的寫，大多都是能拖就拖，拖不了就草草應付，固然我當年也是其中的一份子o(∩_∩)o

 

　　爲何不少程序員會很抗拒寫文檔？

　　這個就再也不詳細描述，大家問問本身就知道了。

 

　　本文的主要是想告訴初學者們，爲何咱們要寫文檔，寫文檔對咱們開發有什麼幫助，以及對各類文檔有個大概的認識。

 

　　好處一：確認需求，減小程序修改工做量

　　不少朋友都碰到過拍腦殼的老闆、客戶或領導（說的很差聽就是頭腦一熱，需求不過夜的人），而這些朋友真的是遍體鱗傷，給虐了一遍又一遍，而我也是屬於那個被虐的人，呵呵......

　　我之前有位同事，在一塊兒共事時每一個項目都要求他寫文檔，當時他一直都以爲很麻煩，後來換了公司後才真正體會到沒文檔的苦惱。他的老闆是那種頗有想法的人，常常會有新點子出來，因此在作項目時，一有新的想法就要求他實現 。而有的想法當時提出後過了一兩天就忘了，那麼他就杯具了......有次他同我說，如今終於明白文檔的重要性了，沒有文檔的日子都不是人過的。

　　需求的不停變更對於程序員來講，是個永遠的痛\(╯^╰)/ ，固然咱們也不能坐以待斃，而需求文檔就是咱們最好的武器（對於那些全部項目都不須要文檔的公司不在本文的討論範圍以內）。具體的需求文檔編寫說明請留意後面的章節。

 

　　好處二：幫助咱們熟悉項目

　　在編寫相關文檔時，其實就是幫助咱們對項目的理解，理順一些算法思路。

　　沒有編寫文檔時，你常常會想固然，內心以爲已經很瞭解整個項目結構與需求了，要怎麼實現也有了想法，而人的記憶是會遺忘的，等開發一段時間後，原來想要實現的功能可能就忘得一乾二淨了。而在編寫文檔的時候，會幫咱們認真的考慮整個需求，對一些要求也會詳細斟酌，從中發現不少咱們沒有想到的問題，而後再深刻的去考慮怎麼解決這些問題，要用什麼算法，會不會再引起更多的問題.....文檔完成後，整個項目其實就等於在你的大腦裏面實現過一次了，在進入開發階段就會比較順風順水，開發效率也會很高效。

 

　　好處三：提升開發效率，防止出錯

　　記得好幾年前在一家手機羣發、扣費公司上班，當時要開發一個功能，能夠在服務器端根據須要控制手機扣費使用渠道、價格...的功能，在接到這個開發需求時，我並非立刻編碼，而是花了四五天時間在整理需求，編寫對應的開發文檔與流程圖，因爲有完善的開發文檔與流程圖（具體請看當時的流程設計圖），只花了一天時間就完成了主要的業務邏輯，一個2K多行的存儲過程（含註釋，後來不斷的添加新業務最後擴展到3K多行），又花了半天開發出手機端調用程序和服務器端調用接口，而最後測試只花了半天時間，修改了幾個小BUG就搞定能夠上線了。上線後頂着常常瞬間幾K併發量壓力，一直運行到公司轉型，二年多時間都沒有出現過什麼問題，爲何這麼複雜的邏輯，但開發佔用時間很短，測試上線後在大併發的壓力下運行都很正常呢？主要的功勞是作足了前期的需求分析與開發文檔編寫，若是沒有的話，嘿嘿......試過的人都知道，你懂的。只有真正瞭解項目需求，理順項目流程，並作了深刻思考，那麼不少常見的問題均可以迎刃而解。

　

　　好處四：控制項目進度

　　若是沒有文檔，開發一個新項目時所定下的開發週期絕大部分都是頗有水份的，有多少能按時完成也是個未知數。

　　而有詳細的文檔說明、數據庫設計、流程圖、功能設計都出來後，這時有經驗的開發人員繪製甘特圖制定的項目開發進度就比較靠譜了。而後開發團隊根據開發計劃，控制好天天完成的功能進度，通常都能按時完成開發要求，就算有誤差也不會太離譜（除非中間需求變更或制定計劃的人經驗不足）。

 

　　好處五：爲後期測試工做提供指引

 　　有了完善的文檔，在進入測試階段時，就能夠根據需求文檔與開發文檔對功能進行測試，編寫測試用例。若是沒有文檔，都不知道初始功能求要是什麼，那隻能測已完成的功能、UI等模塊了。

 

　　好處六：爲二次開發與軟件維護提供支持

 　　在上一文中已說過相關例子，沒有文檔資料、缺乏註釋，而代碼又不規範的話，那就是一個大坑，一個很難填平的黑坑。

 

　　...... （其餘幫助）

　　除了以上好處外，對於初學者來講，能編寫一份好文檔，並配合相應的成功做品，這將是你職業生涯最好的敲門磚，能提升你自身的價值和應聘成功機率。

 

　　不是任什麼時候候都須要編寫規範的文檔
　　固然不是任何項目都須要編寫文檔的，對於小公司小項目，開發人員只有一兩我的的話，爲了追求快速出產品，快速上線，特別是有一個好框架的狀況下，沒有文檔也並非大不了的事情。

　　不一樣公司有不一樣的文檔編寫要求，而格式也是大不相同。對於要求比較規範的大公司，這些文檔的編寫大都會嚴格的按軟件工程要求的格式來，固然這樣作的話沒有必定經驗，寫起來會比較吃力，花的時間也比較長，而當今的網絡社會是快魚吃慢魚的時代，對於中小公司或我的開發，若是花太多時間的話，那就得不償失了，因此仍是根據具體狀況而定，編寫的文檔格式與要求相應作出調整。

 

　　對於初學者文檔應該怎麼編寫呢？使用什麼模板或格式？

　　在一個項目從開始提出需求到實施結束，這個過程會涉及不少文檔的編寫，在編寫的過程當中，對於初學者來講並很差把握，經常會不知道使用什麼格式、排版，內容要怎麼來寫。

　　通常來講通用的模板內容大都內容全面、詳細，比較複雜，初學者沒有經驗寫起來會比較吃力。因此編寫時可使用通用模板進行模仿，但不用所有照搬。

　　實際上編寫文檔就像寫做文，只要條理清晰的講述出相關內容，突出重點，不要偏離該文檔主題就能夠了。固然若是你能詳細的將5個W2H原則說明清楚，再配上相應的圖例（流程圖），那就更棒了。

　　5個W2H原則說明：1.WHY ——爲何？爲何要這麼作？理由何在？緣由是什麼？2. WHAT——是什麼？目的是什麼？作什麼工做？3. WHERE——何處？在哪裏作？從哪裏入手？4.WHEN——什麼時候？什麼時間完成？什麼時機最適宜？5. WHO——誰？由誰來承擔？誰來完成？誰負責？6.HOW——怎麼作？如何提升效率？如何實施？方法怎樣？7. HOW MUCH——多少？作到什麼程度？須要多少時間？數量如何？質量水平如何？費用產出如何？

　　不一樣文檔的主題是什麼？

　　需求文檔主要是爲了讓實施方瞭解軟件開發完成後要達到的效果，以及和需求方對軟件功能進行文檔確認。

　　概要設計（整體設計）文檔主要是爲了和需求方進一步確認需求，以及軟件設計的功能是否設置合理。同時也做爲後面詳細功能設計、數據庫設計以及其餘相關設計的整體指導，瞭解開發過程當中須要使用的基本算法，以及可能遇到的問題。也方便將詳細設計以及相關設計任務進行切分，分配給不一樣的負責人共同編寫，減小花費時間。

　　詳細設計文檔主要是將整體設計裏所講述的內容進行細化，詳細描述所要實現的功能、算法以及流程圖。細化到每一個頁面要放置什麼按鈕、字段，列表中要顯示什麼內容，頁面要實現什麼功能，而實現這些功能可能要使用什麼算法等。當寫完詳細設計後整個項目基本上就出來了。

　　數據庫設計是一個很重要的環節，由於好的設計會給整個系統帶好良好的性能，爲開發過程當中減小沒必要要的代碼，提升開發效率有着很重要的幫助。數據庫設計是根據詳細設計裏所描述的內容轉換成開發中的數據表與字段。而在進行數據庫設計時，經常會發現不少以前沒有考慮到的問題，會有不少新的想法與需求，須要添加新的字段，這時在添加的時候必須進行反覆斟酌，判斷是不是必須添加的，是否必須在第一期開發中實現？可否放在第二期開發？對開發時間有沒有影響？影響有多大？由於不少新的想法與擴展都不是必須的，不少想法也需求實現後都沒有真正使用到，這樣的話就浪費時間。咱們必需要按計劃與需求來進行開發，而不是隨意的添加新的功能進來，這樣才能作好開發進度的把控工做。而添加後必須同步更新詳細設計文檔，補充新添加的字段或功能描述。
　　
　　項目開發計劃（甘特圖）文檔，主要是將詳細設計裏的每一個功能，在實施時進行開發人員，以及開發前後順序安排，並確認所需時間，制定開發計劃。

 

　　單元測試文檔，主要是編寫各類測試用例，包括各類極限用例的提交以及返回結果的預期文檔，幫助測試人員以及開發人員完善功能設計。

 

　　部署文檔主要是將發佈到生產環境的操做步驟以及注意事項進行詳細描述，方便相關管理人員能輕鬆的部署最終上線版本，出現問題時快速找出並解決問題。

　　

　　除了上面所描述的文檔外，還有不少各類各樣的文檔，固然大部分都不是本系列所要涉及的內容，因此暫時就再也不深刻描述，若是有須要再開單章進行細說。

 

　　固然實現開發中並不可能很理想化，將上面提到的文檔或步驟來實施，而真正的多是儘量的壓縮你的文檔時間（甚至沒有文檔），壓縮你的開發時間，以便能快速產出上線，固然對於小型企業網站或軟件來講問題不是很大，而稍微大些的項目，在測試階段就會很是的頭痛了，各類沒有考慮到的BUG接踵而來，開始進行扯皮。因此說能規範的話儘可能規範，有可能編寫文檔的話，儘可能將文檔補齊，這樣會減小後期大量的工做，就算有問題進行扯皮的時候，起碼有文字性的記載。而對於那些必須的變更要求，那也能讓需求方知道你作了多少事情，用了多少工做量，而不是給他們感受才改了這一點點需求，沒什麼大不了的，由於需求方大部分人都不知道你碼代碼時所花費的工做量與付出。

　　相關文檔的詳細格式與內容，請留意後面的相應章節。
　　

 版權聲明：

　　本文由AllEmpty原創併發佈於博客園，歡迎轉載，未經本人贊成必須保留此段聲明，且在文章頁面明顯位置給出原文連接，不然保留追究法律責任的權利。若有問題，能夠經過1654937@qq.com 聯繫我，很是感謝。

　　發表本編內容，只要主爲了和你們共同窗習共同進步，有興趣的朋友能夠加加Q羣：327360708 或Email給我（1654937@qq.com），你們一塊兒探討。

　　更多內容，敬請觀注博客：http://www.cnblogs.com/EmptyFS/