計算機軟件產品開發文件編制指南

計算機軟件產品開發文件編制指南（GB 8567-88）之一  　應廣大網友的要求，從今天開始，51CMM.COM軟件文檔欄目將陸續刊登國家有關計算機軟件產品開發文件編制指南（GB 8567-88）。這只是一個國家標準，並不必定適合每個企業，各企業（組織）應該按照標準，制訂出符合自身軟件過程規範的文檔要求。 引言 1 目的 　　一項計算機軟件的籌劃、研製及實現，構成一個軟件開發項目。一個軟件開發項目的進行，通常須要 在人力和自動化資源等方面做重大的投資。爲了保證項目開發的成功，最經濟地花費這些投資，而且便 於運行和維護，在開發工做的每一階段，都須要編制二定的文件。這些文件連同計算機程序及數據一塊兒， 構成爲計算機軟件。文件是計算機軟件中不可缺乏的組成部分，它的做用是： 　　a．做爲開發人員在必定階段內的工做成果和結束標誌； 　　b．向管理人員提供軟件開發過程當中的進展和狀況，把軟件開發過程當中的一些"不可見的"事物轉 換成"可見?quot;文字資料。以便管理人員在各個階段檢查開發計劃的實施進展，使之可以判斷原定目標是 否已達到，還將繼續耗用資源的種類和數量； 　　C．記錄開發過程當中的技術信息，便於協調之後的軟件開發、使用和修改； 　　d．提供對軟件的有關運行、維護和培訓的信息，便於管理人員、開發人員、操做人員和用戶之間相 互瞭解彼此的工做； 　　e．向潛在用戶報導軟件的功能和性能，使他們能斷定該軟件可否服務於本身的須要。 　　換言之，本指南認爲：文件的編制必須適應計算機軟件整個生存週期的須要。 　　計算機軟件所包含的文件有兩類：一類是開發過程當中填寫的各類圖表，可稱之爲工做表格；另外一類 則是應編制的技術資料或技術管理資料，可稱之爲文件。本指南規定軟件文件的編制形式，並提供對這 些規定的解釋。本指南的目的是使得所編制的軟件文件確實可以起到軟件文件應該發揮的做用。 2 範圍 　　本指南是一份指導性文件。本指甫建議，在一項計算機軟件的開發過程當中，通常地說，應該產生十四 種文件。這十四種文件是： 　　可行×××報告； 　　項目開發計劃； 　　軟件需求說明書； 　　數據要求說明書； 　　概要設計說明書； 　　詳細設計說明書； 　　數據庫設計說明書； 　　用戶手冊； 　　操做手冊； 　　模塊開發卷宗； 　　測試計劃； 　　測試分析報告； 　　開發進度月報； 　　項目開發總結報告。 　　本指南將給出開發過程當中建議產生的這十四種文件的編制指導，同時，本指南也是這十四種文件的 編寫質量的檢驗準則。可是，本指南並未涉及軟件開發過程當中如何填寫工做表格的問題。 　　通常地說，一個軟件老是一個計算機系統（包括硬件、固件和軟件）的組成部分。鑑於計算機系統的 多樣性，本指南通常不涉及整個系統開發中的文件編制問題，本指南僅僅是軟件開發過程當中的文件編制指南。 3 文件的使用者 　　對於使用文件的人員而言，他們所關心的文件的種類，隨他們所承擔的工做而異。 　　管理人員：可行×××報告，項目開發計劃，模塊開發卷宗，開發進度月報，項目開發總結報告； 　　開發人員：可行×××報告，項目開發計劃，軟件需求說明書，數據要求說明書， 概要設計說明書，詳細設計說明書，數據庫設計說明書，測試計劃，測試分析報告； 　　維護人員：設計說明書，測試分析報告，模塊開發卷宗； 　　用戶：用戶手冊， 操做手冊。 　　儘管本指南提出了在軟件開發中文件編制的要求，但並不意味着這些文件都必須交給用戶。一項軟件的用戶應該獲得的文件的種類由供應者與用戶之間簽定的合同規定。   第一篇 文件的編制指導 4 軟件生存週期與各類文件的編制 　　一項計算機軟件，從出現一個構思之日起，通過這項軟件開發成功投入使用，直到最後決定中止使 用，並被另外一一項軟件代替之時止，被認爲是該軟件的一個生存週期。通常地說這個軟件生存週期能夠分紅如下六個階段： 　　可行性與計劃研究階段 　　需求分析階段 　　設計階段 　　實現階段 　　測試階段 　　運行與維護階段 　　在可行×××與計劃階段內，要肯定該軟件的開發目標和總的要求，要進行可行性分析、投資一收益分析、制訂開發計劃，並完成應編制的文件。 　　在需求分析階段內，由系統分析人員對被設計的系統進行系統分析，肯定對該軟件的各項功能、性能需求和設計約束，肯定對文件編制的要求，做爲本階段工做的結果，通常地說，軟件需求說明書、數據要求說明書和初步的用戶手冊應該編寫出來。 　　在設計階段內，系統設計人員和程序設計人員應該在反覆理解軟件需求的基礎上，提出多個設計，分析每一個設計能履行的功能並進行相互比較，最後肯定一個設計，包括該軟件的結構、模塊的劃分、功能的分配以及處理流程。在被設計系統比較複雜的狀況下，設計階段應分解成概要設計階段和詳細設計階段兩個步驟。在通常狀況下，應完成的文件包括：概要設計說明書、詳細設計說明書和測試計劃初稿。 　　在實現階段內，要完成源程序的編碼、編譯（或彙編）和排錯調試獲得無語法錯的程序清單，要開始編寫模塊開發卷宗，而且要完成用戶手冊、操做手冊等面向用戶的文件的編寫工做，還要完成測試計劃的編制。 　　在測試階段，該程序將被全面地測試，已編制的文件將被檢查審閱。通常要完成模塊開發卷宗和測試分析報告，做爲開發工做的結束，所生產的程序、文件以及開發工做自己將逐項被評價，最後寫出項目開發總結報告。 　　在整個開發過程當中（即前五個階段中），開發集體要按月編寫開發進度月報。 　　在運行和維護階段，軟件將在運行使用中不斷地被維護，根據新提出的需求進行必要並且可能的擴充和刪改。 　　對於一項軟件而言，其生存週期各階段與各類文件編寫工做的關係可見表互，其中有些文件的編寫工做可能要在若干個階段中延續進行。 表1軟件生存週期各階段中的文件編制  5 文件編制中的考慮因素 　　文件編制是一個不斷努力的工做過程。是一個從造成最初輪廓，經反覆檢查和修改，直到程序和文件正式交付使用的完整過程。其中每一步都要求工做人員作出很大努力。要保證文件編制的質量，要體現每一個開發項目的特色，也要注意不要花太多的人力。爲此，編制中要考慮以下各項因素。 5．1 文件的讀者 　　每一種文件都具備特定的讀者。這些讀者包括我的或小組、軟件開發單位的成員或社會上的公衆、從事軟件工做的技術人員、管理人員或領導幹部。他們期待着使用這些文件的內容來進行工做，例如設計、編寫程序、測試、使用、維護或進行計劃管理。所以，這些文件的做者必須瞭解本身的讀者，這些文件的編寫必須注意適應本身的特定讀者的水平、特色和要求。 5．2 重複性 　　本指南第二篇中將列出的這十四種文件的內容要求中，顯然存在某些重複。較明顯的重複有兩類。引言是每一種文件都要包含的內容，以向讀者提供總的梗概。第二類明顯的重複是各類文件中的說明部分，如對功能性能的說明、對輸入和輸出的描述、系統中包含的設備等。這是爲了方便每種文件各自的讀者，每種產品文件應該自成體系，儘可能避免讀一種文件時又不得不去參考另外一種文件。固然，在每一種文件裏，有關引言、說明等同其餘文件相重複的部分，在行文上、在所用的術語上、在詳細的程度上，仍是應該有一些差異，以適應各類文件的不一樣讀者的須要。 5．3 靈活性 　　鑑於軟件開發是具備創造性的腦力勞動，也鑑於不一樣軟件在規模上和複雜程度上差異極大，本指南認爲在文件編制工做中應容許必定的靈活性。這種靈活性表如今以下各款。 5．3．1 應編制的文件種類 　　儘管本指南認爲在通常狀況下，一項軟件的開發過程當中，應產生的文件有十四種，然而針對一項具體的軟件開發項目，有時沒必要編制這麼多的文件，能夠把幾種文件合併成一種。通常地說，當項目的規模、複雜性和成敗風險增大時，文件編制的範圍、管理手續和詳細程度將隨之增長。反之，則可適當減小。爲了恰當地掌握這種靈活性，本指南要求貫徹分工負責的原則，這意味着： 　　a: 一個軟件開發單位的領導機構應該根據本單位經營承包的應用軟件的專業領域和本單位的管理能力，制定一個對文件編制要求的實施規定，主要是：在不一樣的條件下，應該造成哪些文件？這些文件的詳細程度？該開發單位的每個項目負責人，必須認真執行這個實施規定。這種規定的兩個例子可嘆 本指南的附錄o（參考件）； 　　b．對於一個具體的應用軟件項目，項目負責人應根據上述實施規定，肯定一個文件編制計劃，主 中包括: 　　（1）應該編制哪幾種文件，詳細程度如何？ 　　（2）各個文件的編制負責人和進度要求； 　　（3）審查、批准的負責人和時間進度安排； 　　（4）在開發時期內，各文件的維護、修改和管理的負責人，以及批准手續。 　　每項工做必須落實到人。 　　這個文件編制計劃是整個開發計劃的重要組成部分； 　　C．有關的設計人員則必須嚴格執行這個文件編制計劃。 5．3．2 文件的詳細程度 　　從同一份提綱起草的文件的篇幅大小每每不一樣，能夠少到幾頁，也能夠長達幾百頁。對於這種差異本指南是容許的。此詳細程度取決於任務的規模、複雜性和項目負責人對該軟件的開發過程及運行環與所須要的詳細程度的判斷。 5．3．3 文件的擴展 　　當被開發系統的規模很是大（例如源碼超過一百萬行）時，一種文件能夠分紅幾卷編寫，能夠按其。 每個系統分別編制，也能夠按內容劃分紅多卷，例如： 　　項目開發計劃可能包括：質量保證計劃，配置管理計劃， 用戶培訓計劃， 安裝實施計劃； 　　系統設計說明書可分寫成：系統設計說明書，子系統設計說明書； 　　程序設計說明書可分寫成：程序設計說明書，接口設計說明書，版本說明； 　　操做手冊可分寫成：操做手冊，安裝實施過程； 　　測試計劃可分寫成：測試計劃，測試設計說明， 測試規程，測試用例； 　　測試分析報告可分寫成：綜合測試報告，驗收測試報告； 　　項目開發總結報告亦可分寫成項目開發總結報告和資源環境統計。 5．3．4 節的擴張與縮並 　　在有些文件中，可使用本指南所提供的章、條標題，但在條內又存在一系列須要分別討論的因素 本指南認爲，全部的條均可以擴展，能夠進一步細分，以適應實際須要。反之，若是章條中的有些細節； 非必需，也能夠根據實際狀況縮並。此時章條的編號應相應地改變。 5．3．5 程序設計的表現形式 　　本指南對於程序的設計表現形式並未做出規定或限制，可使用流程圖的形式、斷定表的形式，1 可使用其餘表現形式，如程序設計語言（PDL）、問題分析圖（PAD）等。 5．3．6 文件的表現形式 　　本指南對於文件的表現形式亦未做出規定或限制，可使用天然語言，也可使用形式化語言。 5．3．7 文件的其餘種類 　　當本指南中規定的文件種類尚不能知足某些應用部門的特殊須要時，他們能夠創建一些特殊的文件種類要求，例如軟件質量保證計劃、軟件配置管理計劃等，這些要求能夠包含在本單位的文件編制實施規定中。 6 文件編制的管理工做 　　文件編制工做必須有管理工做的配合，才能使所編制的文件真正發揮它的做用。文件的編制工做實際上貫穿於一項軟件的整個開發過程，所以，對文件的管理必須貫穿於整個開發過程。在開發過程當中必須進行的管理工做是如下四條。 6．1文件的造成 　　開發集體中的每一個成員，尤爲是項目負責人，應該認識到：文件是軟件產品的必不可少的組成部分；在軟件開發過程的各個階段中，必須按照規定及時地完成各類產品文件的編寫工做；必須把在一個開發步驟中做出的決定和取得的結果及時地寫入文件；開發集體必須及時地對這些文件進行嚴格的評審；這些文件的造成是各個階段開發工做正式完成的標誌。這些文件上必須有編寫者、評審者和批准者的簽字，必須有編寫、評審完成的日期和批准的日期。 6．2文件的分類與標識 　　在軟件開發的過程當中，產生的文件是不少的，爲了便於保存、查找、使用和修改，應該對文件按層次地加以分類組織。一個軟件開發單位應該創建一個對本單位文件的標識方法，使文件的每一頁都具備明確的標識。例如能夠按以下四個層次對文件加以分類和標識。 　　a．文件所屬的項目的標識； 　　b．文件種類的標識； 　　C．同一種文件的不一樣版本號； 　　d．頁號。 　　此外，對每種文件還應根據項目的性質，劃定它們各自的保密級別，肯定他們各自的發行範圍。 6．3文件的控制 　　在一項軟件的開發過程當中，隨着程序的逐步造成和逐步修改，各類文件亦在不斷地產生、不斷地修改或補充。所以，必須加以周密的控制，以保持文件與程序產品的一致性，保持各類文件之間的一致性和文件的安全性。這種控制表現爲： 　　a．就從事一項軟件開發工做的開發集體而言，應設置一位專職的文件管理人員（接口管理工程師或文件管理員）；在開發集體中，應該集中保管本項目現有所有文件的主文本兩套，由該文件管理人員負責保管； 　　b．每一份提交給文件管理人員的文件都必須具備編寫人、審覈人和批准人的簽字； 　　C．這兩套主文本的內容必須徹底一致；其中有一套是可供出借的，另外一套是絕對不能出借的，以避免發生萬一；可出借的主文本在出借時必須辦理出藉手續，歸還時辦理註銷出借手續； 　　d．開發集體中的工做人員能夠根據工做的須要，在本項目的開發過程當中持有一些文件，即所謂我的文件，包括爲使他完成他承擔的任務所須要的文件，以及他在完成任務過程當中所編制的文件；但這種我的文件必須是主文本的複製品，必須同主文本徹底一致，若要修改，必須首先修改主文本； 　　e．不一樣開發人員所擁有的我的文件一般是主文本的各類子集；所謂子集是指把主文本的各個部分根據承擔不一樣任務的人員或部門的工做須要加以複製、組裝而成的若干個文件的集合；文件管理人員。應該列出一份不一樣子集的分發對象的清單，按照清單及時把文件分發給有關人員或部門； 　　f．一份文件若是已經被另外一份新的文件所代替，則原文件應該被註銷；文件管理人中要隨時整理主文本，及時反映出文件的變化和增長狀況，及時分發文件； 　　g．當一個項目的開發工做臨近結束時，文件管理人員應逐個收回開發集體內每一個成員的我的文 件，並檢查這些我的文件的內容；經驗代表，這些我的文件每每可能比主文本更詳細，或同主文本的內容 有所不一樣，必須認真監督有關人員進行修改，使主文本能真正反映實際的開發結果。 6．4文件的修改管理 　　在一個項目的開發過程當中的任什麼時候刻，開發集體內的全部成員均可能對開發工做的已有成果-- 文件，提出進行修改的要求。提出修改要求的理由多是各類各樣的，進行修改而引發的影響可能很小， 也可能會牽涉到本項目的不少方面。所以，修改活動的進行必須謹慎，必須對修改活動的進行加以管理， 必須執行修改活動的規程，使整個修改活動有控制地進行。 　　修改活動可分以下五個步驟進行： 　　a．提議開發集體中的任何一個成員均可以向項目負責人提出修改建議，爲此應該填寫一份修 改建議表，說明修改的內容、所修改的文件和部位、以及修改理由； 　　b．評議由項目負責人或項目負責人指定的人員對該修改建議進行評議，包括審查該項修改的 必要性、肯定這一修改的影響範圍、研究進行修改的方法、步驟和實施計劃； 　　c．審覈通常由項目負責人進行審覈，包括覈實修改的自的和要求、覈實修改活動將帶來的影 響、審覈修改活動計劃是否可行； 　　d．批准在通常狀況下，批准權屬於該開發單位的部門負責人；在批准時，主要是決斷修改工做 中各項活動的前後順序及各自的完成日期，以保證整個開發工做按原定計劃日期完成； 　　e．實施由項目負責人按照已批准的修改活動計劃，安排各項修改活動的負責人員進行修改，建 立修改記錄、產生新的文件以取代原有文件、最後把文件交文件管理人員歸檔，並分發給有關的持有者。