軟件文檔寫作標準講義

軟件文檔寫作⑴問題定義 （書面）⑵可行性分析報告 （書面）⑶項目開發(fā)計劃 （書面）⑷需求規(guī)格說明書 （書面）⑸總體設計報告 （書面）⑹系統(tǒng)測試計劃 （書面）⑺項目驗收方案 （書面）

要求：根據(jù)軟件工程技術和項目管理理念，在組內(nèi)合理分工，協(xié)同工作。軟件文檔文檔是計算機軟件產(chǎn)品的重要組成部分，沒有文檔就不成其為軟件，也更不能成為軟件產(chǎn)品。軟件文檔是一種重要的軟件工程技術資料。如系統(tǒng)分析文檔、設計文檔、版本說明文檔……軟件文檔的規(guī)范編制，在軟件開發(fā)工作中占有突出的地位和相當大的工作量。高質(zhì)量、高效率的編制、分發(fā)、管理、維護文檔，及時的變更、修正、擴充和使用文檔，對于軟件產(chǎn)品的設計開發(fā)、發(fā)行使用、變更維護、轉(zhuǎn)讓移植、二次開發(fā)等，對于充分發(fā)揮軟件產(chǎn)品的效益，都有著重要的意義。軟件文檔的分類基于軟件生存期方法，可以從形式上將軟件文檔大致分成兩類：軟件開發(fā)過程中需要填寫的各種圖表，及應編制的各種技術文件或管理資料。軟件文檔根據(jù)其產(chǎn)生和使用的范圍，主要劃分為3大類：開發(fā)文檔、用戶文檔和管理文檔。軟件文檔開發(fā)文檔用戶文檔管理文檔可行性研究報告項目開發(fā)計劃軟件需求說明書數(shù)據(jù)庫設計說明書概要設計說明書詳細設計說明書用戶手冊操作手冊軟件需求說明書數(shù)據(jù)要求說明書項目開發(fā)計劃模塊開發(fā)卷宗開發(fā)進度月報測試計劃測試分析報告項目開發(fā)總結報告開發(fā)文檔用戶文檔軟件文檔的使用對象開發(fā)人員維護人員管理人員用戶可行性研究報告項目開發(fā)計劃軟件需求說明書數(shù)據(jù)要求說明書概要設計說明書詳細設計說明書數(shù)據(jù)庫設計說明書測試計劃測試分析報告設計說明書測試分析報告模塊開發(fā)卷宗可行性研究報告項目開發(fā)計劃模塊開發(fā)卷宗開發(fā)進度月報項目開發(fā)總結報告用戶手冊操作手冊可行性研究與計劃需求分析軟件設計編碼與單元測試集成與測試運行與維護可行性研究報告√項目開發(fā)計劃√√軟件需求說明書√數(shù)據(jù)要求說明書√測試計劃√√概要設計說明書√詳細設計說明書√數(shù)據(jù)庫設計說明書√模塊開發(fā)卷宗√√用戶手冊√√√操作手冊√√測試分析報告√開發(fā)進度月報√√√√√項目總結報告√維護和修改建議√軟件生存周期各個階段與各種文檔編制的關系為什么(Why)做什么(What)怎么做(How)誰來做(Who)何時做(When)何處做(Where)可行性研究報告√√項目開發(fā)計劃√√√軟件需求說明書√√數(shù)據(jù)要求說明書√√測試計劃√√√概要設計說明書√詳細設計說明書√數(shù)據(jù)庫設計說明書√模塊開發(fā)卷宗√用戶手冊√操作手冊√測試分析報告√開發(fā)進度月報√√項目總結報告√維護和修改建議√√√√√文檔所回答的問題軟件工程標準化和軟件文檔標準軟件工程標準編制的層次根據(jù)軟件工程標準制定的機構和標準適用的范圍，可分為5個層次：國際標準:ISO國際標準化組織國家標準:GB中國ANSI美國BS英國JIS日本行業(yè)標準:IEEE企業(yè)(機構)標準:IBM項目(課題)標準:CIMS類型標準名稱標準號基礎標準軟件工程術語GB/T11457-1989信息處理——數(shù)據(jù)流程、程序流程圖、系統(tǒng)結構圖、程序網(wǎng)絡圖、系統(tǒng)資源圖的文件編制符號及約定GB/T1526-1989軟件工程標準分類法GB/T15538-1995信息處理——程序構造及其表示法的約定GB/T13502-1992信息處理——單命中判定表規(guī)范GB/T15535-1995(ISO5806)信息處理系統(tǒng)——計算機系統(tǒng)配置圖符號及其約定GB/T14085-1993(ISO8790)開發(fā)標準信息技術——軟件生存期過程GB/T8566-1995軟件支持環(huán)境GB/T15853-1995信息處理——按記錄組處理順序文卷的程序流程GB/T15697-1995(ISO6593)軟件維護指南GB/T14079-1993文檔標準計算機軟件產(chǎn)品開發(fā)文檔編制指南GB/T8567-1988計算機軟件需求說明編制指南GB/T9385-1988計算機軟件測試文檔編制規(guī)范GB/T9386-1988軟件文檔管理指南GB/T16680-1996管理標準計算機軟件配置管理計劃規(guī)范GB/T12505-1990信息技術——軟件產(chǎn)品評價質(zhì)量特性及其使用指南GB/T16260-1996計算機軟件質(zhì)量保證計劃規(guī)范GB/T12504-1990計算機軟件可靠性和可維護性管理GB/T14394-1993文檔表達合理文檔的7條規(guī)則1.從讀者的角度編寫文檔2.避免出現(xiàn)不必要的重復3.避免歧義4.使用標準結構5.記錄基本原理6.使文檔保持更新，但頻度不要過高7.針對目標的適宜性對文檔進行評審

下表是各類文檔涉眾以及他們需要的文檔類型(部分)：開發(fā)人員維護人員管理人員營銷人員用戶可行性研究報告√√√項目開發(fā)計劃√√√軟件需求說明書√√數(shù)據(jù)要求說明書√測試計劃√√概要設計說明書√√詳細設計說明書√√數(shù)據(jù)庫設計說明書√√模塊開發(fā)卷宗√√用戶手冊√√操作手冊√√測試分析報告√√開發(fā)進度月報√項目總結報告√維護和修改建議√產(chǎn)品市場宣傳資料√√√（1）用求和法確定應編制的文檔該方法的要點是提出12個考慮因素來衡量一個應用軟件，以及每個因素可能取值的范圍。任務負責人可用這12個因素對所要開發(fā)的程序進行衡量，以確定每個因素的具體值。然后，把這12個因素的值相加，得到一個總和，就可以根據(jù)這個總和的值，來確定應該編制的文檔的種類。編號因素因素取值123451創(chuàng)新程度沒有－在不同設備上重編程序有限－只是具有更嚴格的要求很多－具有新的接口大量－應用新的現(xiàn)代開發(fā)技術重大－應用先進的開發(fā)和管理技術2通用程度很強的限制－單一項目有限制－功能的范圍是參量化的有限的靈活性，允許格式上有些變化多用途、靈活的格式、有主題領域很靈活－能在不同設備上處理范圍廣泛的主題3應用范圍局部單位(團以下)本地應用(師級)行業(yè)推廣(軍級)全國推廣(大軍區(qū))國際項目(全軍范圍)4應用環(huán)境的變化沒有很少偶爾有經(jīng)常不斷5設備復雜性單機、常規(guī)處理單機、常規(guī)處理、擴充的外設系統(tǒng)多機、標準的外設系統(tǒng)多機、復雜準的外設系統(tǒng)和顯示主機控制系統(tǒng)多機自動I/O6參加開發(fā)人數(shù)1~2人3～5人6～13人11~18人19以上7開發(fā)投資(人月)<66~3636~120120~360>3608重要程度一般數(shù)據(jù)處理常規(guī)過程控制人身安全單位成敗國家安危9完成程序修改的平均時間2周以上1～2周3～7天1～3天24小時以內(nèi)10數(shù)據(jù)I/O平均時間2周以上1～2周1～7天1～24小時1小時以內(nèi)11編程語言高級語言高級語言帶少量的匯編高級語言帶相當多的匯編匯編語言機器語言12并行軟件開發(fā)沒有有限中等程度很多全部然后，將上表衡量所得的各個因素的值相加，得總和值。再根據(jù)下表，確定應編制的文檔種類?？尚行匝芯繄蟾骓椖块_發(fā)計劃軟件需求說明書數(shù)據(jù)要求說明書概要設計說明書詳細設計說明書測試計劃用戶手冊操作手冊測試分析報告開發(fā)進度月報項目開發(fā)總結程序維護手冊12～18√√*√16～26√√**√√√√√√24～38√√√**√√√√√√√36～50√√√**√√√√√√√√48～60√√√**√√√√√√√√√文檔的種類因素值總和表中：*，表示此文檔應編制，但不必太正規(guī)；**，表示應根據(jù)所開發(fā)軟件的實際需要來確定是否需要編制此文檔。（2）根據(jù)軟件規(guī)模大小確定應編制的文檔為了避免在軟件開發(fā)過程中文檔編制的不足或過分，也為了避免前一種方法中對某些因素的把握出現(xiàn)誤判，一個簡便的方法是，把對軟件文檔的編制要求同軟件的規(guī)模聯(lián)系起來。這就是本例的出發(fā)點。這里，我們把軟件的規(guī)模分為四級：(1)小規(guī)模軟件，源碼行數(shù)小于5000；(2)中規(guī)模軟件，源碼行數(shù)約10000～50000；(3)大規(guī)模軟件，源碼行數(shù)約100000～500000；(4)超大規(guī)模軟件，源碼行數(shù)大于500000。對此，相應規(guī)模軟件應該編制的文檔種類，參見下表：小規(guī)模軟件中規(guī)模軟件大規(guī)模軟件超大規(guī)模軟件軟件需求與開發(fā)計劃項目開發(fā)計劃可行性報告對應大規(guī)模軟件所規(guī)定的文檔種類，再做進一步細分項目開發(fā)計劃軟件需求說明軟件需求說明數(shù)據(jù)要求說明測試計劃測試計劃軟件設計說明軟件設計說明概要設計說明詳細設計說明數(shù)據(jù)庫設計說明使用說明使用說明用戶手冊操作手冊測試分析報告模塊開發(fā)卷宗模塊開發(fā)卷宗測試分析報告測試分析報告項目開發(fā)總結開發(fā)進度月報開發(fā)進度月報項目開發(fā)總結項目開發(fā)總結對于源碼行數(shù)在5000～10000、50000～100000的軟件，其文檔編制的種類介于兩級之間，可由項目負責人根據(jù)項目的具體情況，參照下表規(guī)定確定。開發(fā)文檔概述開發(fā)文檔是描述軟件開發(fā)過程，包括軟件需求、軟件設計、軟件測試、保證軟件質(zhì)量的一類文檔，開發(fā)文檔也包括軟件的詳細設計描述(程序邏輯、程序間相互關系、數(shù)據(jù)格式和存儲等)?；镜能浖_發(fā)文檔主要有：可行性研究和項目任務書需求規(guī)格說明功能規(guī)格說明設計規(guī)格說明，包括程序和數(shù)據(jù)規(guī)格說明開發(fā)計劃軟件集成和測試計劃質(zhì)量保證計劃、標準、進度安全和測試信息

[項目名稱]可行性研究報告擬制人______________審核人______________批準人______________[200年月日]

可行性研究報告模板的例子：1.引言1.1編寫目的1.2背景1.3定義1.4參考資料2.可行性研究的前提2.1要求2.2目標2.3條件、假定和限制2.4進行可行性研究的方法2.5評價尺度3.對現(xiàn)有系統(tǒng)的分析3.1處理流程和數(shù)據(jù)流程3.2工作負荷3.3費用開支3.4人員3.5設備3.6局限性4.所建議的系統(tǒng)4.1對所建議系統(tǒng)的說明4.2處理流程和數(shù)據(jù)流程4.3改進之處4.4影響4.4.1對設備的影響4.4.2對軟件的影響4.4.3對用戶單位機構的影響4.4.4對系統(tǒng)運行過程的影響4.4.5對開發(fā)的影響4.4.6對地點和設施的影響4.4.7對經(jīng)費開支的影響

4.5局限性4.6技術條件方面的可行性5.可選擇的其他系統(tǒng)方案5.1可選擇的系統(tǒng)方案15.2可選擇的系統(tǒng)方案26.投資及效益分析6.1支出6.1.1基本建設投資6.1.2其他一次性支出6.1.3非一次性支出6.2收益6.2.1一次性收益6.2.2非一次性收益6.2.3不可定量的收益6.3收益／投資比6.4投資回收周期6.5敏感性分析7.社會因素方面的可行性

7.1法律方面的可行性7.2使用方面的可行性8.結論軟件需求文檔的內(nèi)容1．引言1.1編寫的目的說明編寫這份需求說明書的目的，指出預期的讀者。1.2背景待開發(fā)的系統(tǒng)的名稱；本項目的任務提出者、開發(fā)者、用戶；該系統(tǒng)同其他系統(tǒng)或其他機構的基本的相互來往關系。1.3定義列出本文件中用到的專門術語的定義和外文首字母組詞的原詞組。1.4參考資料列出用得著的參考資料。2．任務概述2.1目標敘述該系統(tǒng)開發(fā)的意圖、應用目標、作用范圍以及其他應向讀者說明的有關該系統(tǒng)開發(fā)的背景材料。解釋被開發(fā)系統(tǒng)與其他有關系統(tǒng)之間的關系。2.2用戶的特點列出本系統(tǒng)的最終用戶的特點，充分說明操作人員、維護人員的教育水平和技術專長，以及本系統(tǒng)的預期使用頻度。2.3假定和約束列出進行本系統(tǒng)開發(fā)工作的假定和約束。3．需求規(guī)定3.1對功能的規(guī)定用列表的方式，逐項定量和定性地敘述對系統(tǒng)所提出的功能要求，說明輸入什么量、經(jīng)怎么樣的處理、得到什么輸出，說明系統(tǒng)的容量,包括系統(tǒng)應支持的終端數(shù)和應支持的并行操作的用戶數(shù)等指標。3.2對性能的規(guī)定3.2.1精度說明對該系統(tǒng)的輸入、輸出數(shù)據(jù)精度的要求，可能包括傳輸過程中的精度。3.2.2時間特性要求說明對于該系統(tǒng)的時間特性要求。3.2.3靈活性說明對該系統(tǒng)的靈活性的要求，即當需求發(fā)生某些變化時，該系統(tǒng)對這些變化的適應能力。3.3輸入輸出要求解釋各輸入輸出數(shù)據(jù)類型，并逐項說明其媒體、格式、數(shù)值范圍、精度等。對系統(tǒng)的數(shù)據(jù)輸出及必須標明的控制輸出量進行解釋并舉例。3.4數(shù)據(jù)管理能力要求(針對軟件系統(tǒng))說明需要管理的文卷和記錄的個數(shù)、表和文卷的大小規(guī)模，要按可預見的增長對數(shù)據(jù)及其分量的存儲要求作出估算。3.5故障處理要求列出可能的軟件、硬件故障以及對各項性能而言所產(chǎn)生的后果和對故障處理的要求。3.6其他專門要求如用戶單位對安全保密的要求，對使用方便的要求，對可維護性、可補充性、易讀性、可靠性、運行環(huán)境可轉(zhuǎn)換性的特殊要求等。4．運行環(huán)境規(guī)定4.1設備列出運行該軟件所需要的硬設備。說明其中的新型設備及其專門功能，包括：處理器型號及內(nèi)存容量外存容量、聯(lián)機或脫機、媒體及其存儲格式，設備的型號及數(shù)量輸入及輸出設備的型號和數(shù)量，聯(lián)機或脫機；數(shù)據(jù)通信設備的型號和數(shù)量功能鍵及其他專用硬件4.2支持軟件列出支持軟件，包括要用到的操作系統(tǒng)、編譯程序、測試支持軟件等。4.3接口說明該系統(tǒng)同其他系統(tǒng)之間的接口、數(shù)據(jù)通信協(xié)議等。4.4控制說明控制該系統(tǒng)的運行的方法和控制信號，并說明這些控制信號的來源。

軟件概要設計文檔結構化表現(xiàn)形式：層次圖示例字處理系統(tǒng)輸入輸出編輯存儲檢索格式化編目錄添加刪除插入修改合并列表簡單的層次圖缺乏追蹤性，而HIPO圖可以彌補此一缺點。1.結構化表現(xiàn)形式結構化表現(xiàn)形式：HIPO圖實際上，HIPO圖是由H圖和IPO圖兩部分組成：H圖就是層次圖；和H圖每個方框相對應的，應該有一張IPO圖描述該方框代表的模塊的處理過程。如下圖，是一個帶編號的H圖的例，具有可追蹤性。字處理系統(tǒng)輸出2.0輸入1.0存儲4.0編輯3.0格式化6.0檢索5.0編目錄7.0刪除3.2添加3.1修改3.4插入3.3列表3.6合并3.5IPO圖使用的符號既少又簡單，能夠方便的描述數(shù)據(jù)輸入、處理和輸出之間的關系。如下圖是一個主文檔更新的IPO例子。程序名：模塊名：編制者：日期：頁號：輸入處理輸出舊的主文件事務文件1.檢驗主記錄2.校驗事務記錄3.更新主記錄有效的主記錄有效的事務記錄更新后的主記錄圖中，箭頭清楚的指出了數(shù)據(jù)通信的情況。結構化表現(xiàn)形式：結構圖Yourdon提出的結構圖是進行軟件結構設計的另一個有力的表達方法。而且，結構圖較之層次圖有更強的描述力。產(chǎn)生最佳解得到好輸入計算最佳解輸出結果讀輸入編輯輸入結果格式化顯示結果好輸入解好輸入解原始輸入原始輸入編輯結束解解的格式化格式化的解結構化表現(xiàn)形式：結構圖結構圖還有一些附加的符號，用以表示模塊的選擇調(diào)用和循環(huán)調(diào)用。如下圖，左圖是選擇調(diào)用，右圖是循環(huán)調(diào)用。

MAB判定為真時調(diào)用模塊A，否則調(diào)用模塊BMACB模塊M循環(huán)調(diào)用模塊A、B、C2、面向?qū)ο笤O計表現(xiàn)形式（1）面向?qū)ο笤O計(OOD)的4個部分這4個部分是問題域、人機交互部分、任務管理部分和數(shù)據(jù)管理部分。如下圖所示。主題層類及對象層結構層屬性層問題域部分人機交互部分任務管理部分數(shù)據(jù)管理部分-問題域部分：OOD根據(jù)需求分析中對問題域的描述，針對實現(xiàn)要求進行必要的整補和調(diào)整。其重點是：重用類設計、組合問題域?qū)Ｓ妙?、調(diào)整繼承的支持級別、提供數(shù)據(jù)管理部分以及增加底層細節(jié)。-人機交互部分設計：突出人如何命令系統(tǒng)，及系統(tǒng)如何向用戶提交信息。尤其對非計算機專業(yè)用戶如何提交信息。-任務管理部分設計：設計策略要點是識別并設計任務，加上包含在每個任務中的服務。-設計管理部分設計：該部分主要是為了隔離數(shù)據(jù)管理方案對系統(tǒng)設計表達的影響。設計既包含數(shù)據(jù)存放方法的設計，也包含相應服務的設計。①繼承機制的表示通常將父類放在上面，將子類放在下面。如左圖AB父類子類派生繼承下圖是表示雞、鴨、貓、狗和動物之間的繼承關系。動物家禽類寵物雞鴨鵝狗貓②聚集關系的表示若類B的定義將類A的對象作為數(shù)據(jù)成員，則B和A之間是一種聚集關系，其表示方法如下圖所示。汽車B輪胎A子午線輪胎③對象關聯(lián)的表示關聯(lián)源對象關聯(lián)指針被關聯(lián)對象屬性Next關聯(lián)對象指針屬性Next關聯(lián)對象指針屬性Next關聯(lián)對象指針被關聯(lián)對象被關聯(lián)對象內(nèi)嵌關聯(lián)結構表示外嵌關聯(lián)結構表示A類對象：A1A類對象：A1A類對象：A2B類對象：B1B類對象：B2B類對象：B3AB關聯(lián)類B類AB類對象關聯(lián)表A類對象標識B類對象標識關聯(lián)對象A1 B1 AB1A1 B2 AB2A2 B1 AB3… … …④注冊/觀察器的表示一種將新的信息一對一的迅速傳送或通知給相關對象的對象協(xié)作機制。特別在分布式環(huán)境中，對象通信代價很高時，這是一種高效的手段，在網(wǎng)絡軟件設計時常用。見下圖例。生產(chǎn)者CollectionClientAttach()Detach()GetData()Generator()Notify()客戶生產(chǎn)者*Gen客戶()～客戶()Update()SetGen()……Notify()……ClientUpdate()…GenAttach()GenDetach()1..n⑤虛擬設備的表示虛擬設備是操作系統(tǒng)的一個重要概念。使用這種概念，可以為在不同設備上實現(xiàn)相同功能，或以相同操作接口訪問不同設備提供可能和方便。如圖ApplicationCanvasDraw()Line()Circle()Rectangle()TextOut()…DrawSpaceDraw()Line()Circle()Rectangle()TextOut()…PrinterDrawSpaceDraw()Line()Circle()Rectangle()TextOut()…PrinterPrewDrawSpaceDraw()Line()Circle()Rectangle()TextOut()…ScreenWinDrawSpaceDraw()Line()Circle()Rectangle()TextOut()…OtherGDI⑥代理結構的表示代理是一種在應用和被訪問對象之間建立的橋梁或關口。通過代理的虛擬作用，達到控制對象訪問的目的。代理具有的作用或特性可以包括間接性、委托性、臨時替代性、虛擬性、安全性/保護性、遠程性和多源性。下圖是代理模式的實現(xiàn)結構表示的例子。ApplicationObjectService()…ActualObjectService()…Object*anObjectService()…ProxyanObjectReturnanObjectService()網(wǎng)絡代理連接的表示例子：應用代理遠程對象多源代理連接的例子應用代理問題求解對象1對象n對象2……連接連接連接連接軟件詳細設計文檔軟件詳細設計文檔詳細設計在概要設計之后，其工作重點是考慮實現(xiàn)各個模塊的規(guī)定功能，表達的是模塊內(nèi)部的邏輯關系、數(shù)據(jù)結構和模塊接口細節(jié)等，表達的方法主要有程序流程圖、N-S圖、PAD圖、PDL語言以及判定表、樹等。①程序流程圖程序流程圖(ProgramFlowChart)的5種基本控制結構：(1)順序結構(sequentialstructure)(2)選擇結構(selectivestructure)ABPBAFT(3)先判定型循環(huán)結構(while-loopstructure)(4)后判定型循環(huán)結構(until-loopstructure)TPSFFSTP(5)多情況選擇(casestructure)TA1FP=1TA2FP=2…TAnFP=n②N-S圖：順序ABPFTAB選擇PFTBDo-WhilePSWhile型循環(huán)Do-UntilPSUntil型循環(huán)Case型選擇P12nA1A2An子過程調(diào)用A③PAD圖(ProblemAnalysisDiagram)：日立公司，1973年提出。為