摘 要：軟件文檔的質(zhì)量是軟件項(xiàng)目質(zhì)量的一部分，規(guī)范的過程管理包括軟件開發(fā)過程的文檔，其規(guī)范及標(biāo)準(zhǔn)化便于開發(fā)過程中準(zhǔn)確地交流信息以及軟件項(xiàng)目交付后的維護(hù)工作，因此可以提高軟件開發(fā)的效率和質(zhì)量、改進(jìn)軟件開發(fā)的過程。本文依據(jù)項(xiàng)目的實(shí)踐經(jīng)驗(yàn)，探討如何實(shí)現(xiàn)開發(fā)文檔的規(guī)范化。指出文檔規(guī)范化的重要性，并且有效地控制變更并對(duì)應(yīng)修改開發(fā)用的文檔即始終保證文檔與代碼的一致性在軟件項(xiàng)目交付使用后的版本升級(jí)及信息系統(tǒng)維護(hù)中更具重要性。

關(guān)鍵詞：軟件開發(fā)文檔；項(xiàng)目質(zhì)量；Offshore；概要設(shè)計(jì)；詳細(xì)設(shè)計(jì)；文檔規(guī)范化；軟件開發(fā)文檔標(biāo)準(zhǔn)化

中圖分類號(hào)：TP311.5

1 軟件開發(fā)文檔的重要性

影響軟件項(xiàng)目進(jìn)度、成本、質(zhì)量的因素主要是“過程、人、技術(shù)”[1]。而規(guī)范的過程管理，包括軟件開發(fā)過程的文檔規(guī)范及標(biāo)準(zhǔn)化便于開發(fā)過程中準(zhǔn)確地交流信息以及軟件項(xiàng)目交付后的維護(hù)工作，因此可以提高軟件開發(fā)的效率和質(zhì)量、改進(jìn)軟件開發(fā)過程。

文檔既然是多人進(jìn)行項(xiàng)目開發(fā)相互溝通及共享信息的媒體，它就是項(xiàng)目所必須的、可重用的、文檔的質(zhì)量也是評(píng)價(jià)項(xiàng)目質(zhì)量的一部分，而且最重要的是文檔是否與源代碼保持一致很重要。

軟件項(xiàng)目的開發(fā)是個(gè)團(tuán)隊(duì)化作業(yè)復(fù)雜的過程，團(tuán)隊(duì)成員間的溝通很重要。目前軟件開發(fā)項(xiàng)目面臨的挑戰(zhàn)是：很多的軟件開發(fā)環(huán)境，應(yīng)用平臺(tái)也很復(fù)雜，有的需求又要在多語言環(huán)境下運(yùn)行。因此保證軟件項(xiàng)目成功的較為重要的一個(gè)因數(shù)之一是軟件開發(fā)過程及其文檔的規(guī)范化管理。文檔是軟件產(chǎn)品的一部分，文檔在軟件設(shè)計(jì)人員、軟件開發(fā)人員、軟件維護(hù)人員及用戶之間起到橋梁的作用。特別是外包開發(fā)的過程中設(shè)計(jì)人員與編程人員往往不在一個(gè)辦公地點(diǎn)，對(duì)系統(tǒng)功能要求的理解除電視會(huì)議，聊天工具，電話等語言視頻溝通外，文檔的溝通很重要，按規(guī)范制作文檔的過程也就是按照軟件開發(fā)的規(guī)范編制軟件的過程。

既然文檔在設(shè)計(jì)及開發(fā)的過程中能在多人多種角色間起到橋梁的作用外，它的編制就必須有助于程序員在編程前能夠理解設(shè)計(jì)書定義的功能定義，有助于項(xiàng)目管理人員監(jiān)督和管理軟件的開發(fā)過程。此外，產(chǎn)品交付后要有助于用戶了解軟件的工作和操作，有助于系統(tǒng)維護(hù)人員對(duì)系統(tǒng)軟件進(jìn)行有效的維護(hù)、修改和功能追加，因此文檔的編制不僅非常重要還必須要保證一定的質(zhì)量。

2 軟件開發(fā)文檔

軟件開發(fā)文檔的種類很多。主要有：功能要求，需求分析，概要設(shè)計(jì)，詳細(xì)設(shè)計(jì)，軟件測(cè)試計(jì)劃，軟件測(cè)試報(bào)告，軟件用戶手冊(cè)，數(shù)據(jù)庫(kù)設(shè)計(jì)，項(xiàng)目可行性分析，項(xiàng)目計(jì)劃，問題管理，項(xiàng)目進(jìn)度管理，項(xiàng)目總結(jié)等許多文檔。軟件開發(fā)規(guī)范（GB 8566-88），軟件產(chǎn)品開發(fā)文件編制指南（GB 8567-88）。

如下開發(fā)工程階段需要的文檔（見表1）：

表1 軟件開發(fā)工程階段的文檔示例

概要設(shè)計(jì)詳細(xì)設(shè)計(jì)單元測(cè)試集成測(cè)試系統(tǒng)測(cè)試軟件交付

概要設(shè)計(jì)說明書詳細(xì)設(shè)計(jì)書單元測(cè)試計(jì)劃集成測(cè)試設(shè)計(jì)書系統(tǒng)測(cè)試計(jì)劃用戶安裝手冊(cè)

DB設(shè)計(jì)說明書 單元測(cè)試報(bào)告集成測(cè)試報(bào)告系統(tǒng)測(cè)試報(bào)告用戶使用指南

3 設(shè)計(jì)書樣式

3.1 用什么文檔編輯軟件書寫設(shè)計(jì)書。發(fā)達(dá)國(guó)家的軟件業(yè)很重視文檔，盡管目前敏捷開發(fā)被一切企業(yè)和開發(fā)團(tuán)隊(duì)所接受，但不可否認(rèn)，對(duì)需求相對(duì)明確，離岸的開發(fā)方式下，大部分的項(xiàng)目目前還是較多地采用瀑布式的開發(fā)方式。

實(shí)踐證明，用Excel書寫設(shè)計(jì)書比用Word書寫更加靈活和高效。本人參與開發(fā)的項(xiàng)目中，絕大部分設(shè)計(jì)書都是用Excel書寫的，Excel特別適用于圖形及表格的表達(dá)方式。而且項(xiàng)目的經(jīng)驗(yàn)是盡量使用圖形及表格的方式來記述設(shè)計(jì)定義，溝通理解的準(zhǔn)確率較高。

3.2 文檔的結(jié)構(gòu)、語言表述及術(shù)語。文檔結(jié)構(gòu)的裝訂順序?yàn)榉饷?、修正履歷、正文、附錄說明。文檔中的層次番號(hào)也要統(tǒng)一，清晰的層次便于閱讀。語言的表達(dá)方式在外包的開發(fā)方式中很重要，因設(shè)計(jì)人員與開發(fā)人員通常不在一個(gè)辦公地點(diǎn)。特別是離岸外包的方式，設(shè)計(jì)人員與開發(fā)人員是不同的母語。因此設(shè)計(jì)書的語言描述應(yīng)盡量使用簡(jiǎn)單句型，不要使用雙重否定，語言描述要清晰準(zhǔn)確盡量不要有二義性。事實(shí)上開發(fā)中出現(xiàn)的錯(cuò)誤在一定比例上是由于設(shè)計(jì)書的理解錯(cuò)誤所造成的。因此語言的表達(dá)應(yīng)盡量使用數(shù)學(xué)邏輯符號(hào)，因?yàn)橹挥袛?shù)學(xué)符號(hào)是跨不同語言的，不易產(chǎn)生理解錯(cuò)誤。如下（見表2）。實(shí)踐證明，僅用語言來表達(dá)，往往易產(chǎn)生理解錯(cuò)誤，用數(shù)學(xué)符號(hào)及數(shù)學(xué)邏輯符號(hào)的溝通最準(zhǔn)確。此外在圖形或表格旁同時(shí)追記語言描述比單單僅用語言來描述其溝通效率更高。

表2 數(shù)學(xué)表達(dá)示例

數(shù)學(xué)表達(dá)

A≠zero and A≠space

B=0 and C=0

D=zero or D=space

X≦0

日付≧yyyy0401

術(shù)語的標(biāo)準(zhǔn)化可提高溝通準(zhǔn)確度和效率的同時(shí)還能提高書寫詳細(xì)設(shè)計(jì)及測(cè)試報(bào)告書的文檔質(zhì)量。因?yàn)樵谕獍_發(fā)中，不能保證所有參與開發(fā)人員的外語水平很高或在同一個(gè)水平上。因此整理術(shù)語詞典，供大家查詢與參考是一個(gè)很好的方法。

將業(yè)務(wù)術(shù)語整理為詞典表，在離岸外包開發(fā)中，比較難的是理解客戶的業(yè)務(wù)及其術(shù)語，隨著業(yè)務(wù)范圍的擴(kuò)大，經(jīng)驗(yàn)的積累，不斷豐富詞典，對(duì)開發(fā)人員迅速理解設(shè)計(jì)書能提供很大的幫助。

3.3 制定編碼規(guī)范及命名規(guī)約。事實(shí)上軟件開發(fā)中，代碼中的注釋也可以理解為是軟件的一部分文檔，而且是很重要的文檔。規(guī)范化代碼中的注釋其本身就是項(xiàng)目質(zhì)量的一部分，因?yàn)樵谀壳暗能浖_發(fā)中，人員的交替是很常見的，好的代碼注釋，對(duì)他人修改程序，特別是系統(tǒng)上線后的項(xiàng)目維護(hù)都很重要。

制定編碼規(guī)范的目的是保證不同開發(fā)人員的代碼風(fēng)格基本一致，降低開發(fā)人員流動(dòng)可能導(dǎo)致的項(xiàng)目風(fēng)險(xiǎn)；強(qiáng)調(diào)代碼的可理解性，強(qiáng)化代碼注釋。

例如VB.Net函數(shù)部分的記述規(guī)則：

'----------------------------------------------------------------

' 概要

' xxxxx

' 參數(shù)的說明

' ARG1 ： 參數(shù)1

' ARG2 ： 參數(shù)2

' 功能說明

' 使用方法說明

' 返回值

' xx 型

' 補(bǔ)充說明

' xxxxx

'----------------------------------------------------------------

變量、常量、函數(shù)、畫面控件及按鈕等都應(yīng)有命名規(guī)則。變量的命名規(guī)則（見表3）

表3 數(shù)據(jù)命名規(guī)則

數(shù)據(jù)類型字首例如

布爾型（Boolean）blnblnxxx

字節(jié)型（Byte）bytbytxxxData

Collection對(duì)象colcolxxx

貨幣類型（Currency）curcurxxx

日期類型（Date）dtmdtmStart

3.4 設(shè)計(jì)書的構(gòu)成。以下是設(shè)計(jì)書的Sheet頁的構(gòu)成示例（見圖4）。

表4 設(shè)計(jì)書的樣例

封面修改履歷功能概要畫面切換關(guān)系畫面設(shè)計(jì)處理流程·處理內(nèi)容DB更新輸入·輸出文件報(bào)表格式輔助說明

無論是概要設(shè)計(jì)還是詳細(xì)設(shè)計(jì)，每本設(shè)計(jì)書要有以下的內(nèi)容：封面、修改履歷、功能概要、畫面的切換關(guān)系、畫面設(shè)計(jì)、處理流程·處理內(nèi)容、DB更新、輸入輸出文件、報(bào)表格式、輔助說明。

一個(gè)功能的設(shè)計(jì)書的應(yīng)盡量集中在一個(gè)Excel文檔中表達(dá)，這樣可提高查找信息的效率，縮短理解設(shè)計(jì)書的時(shí)間。如果分散在幾個(gè)文檔的話，不易查找信息。因?yàn)榫幊淌莻€(gè)腦力工作并且側(cè)重邏輯思維的過程，理解設(shè)計(jì)書的過程中如果還需要參照其他文檔的話則思路很容易被打斷。

另外一些設(shè)計(jì)的細(xì)節(jié)也盡量在文檔中體現(xiàn)，不然開發(fā)者與設(shè)計(jì)者要溝通確認(rèn)很浪費(fèi)時(shí)間。為節(jié)省書寫設(shè)計(jì)文檔的時(shí)間，一些不同功能、不同畫面所共同的地方可以提煉到一個(gè)共同的設(shè)計(jì)書中。這樣也便于文檔的變更修改與維護(hù)。

比如（見表5）是一種畫面項(xiàng)目的定義格式。登錄數(shù)據(jù)時(shí)畫面的項(xiàng)目是否要做必須輸入的檢查？打開畫面時(shí)初期光標(biāo)應(yīng)放在哪個(gè)項(xiàng)目的位置上？該項(xiàng)目的顯示文字的位數(shù)？這些細(xì)節(jié)都應(yīng)該明確。在設(shè)計(jì)之前就將設(shè)計(jì)書的文檔格式標(biāo)準(zhǔn)化，設(shè)計(jì)人員應(yīng)該考慮什么？應(yīng)該明確什么？就很清晰。

一個(gè)軟件項(xiàng)目的成功與失敗，往往不僅限于功能實(shí)現(xiàn)了就可以了，許多情況是細(xì)節(jié)決定成敗。實(shí)施文檔等標(biāo)準(zhǔn)化，可以避免漏記、提高溝通的準(zhǔn)確度從而提高效率及提高質(zhì)量。盡管規(guī)范化的文檔不能完全保證設(shè)計(jì)的質(zhì)量，設(shè)計(jì)的質(zhì)量主要還要依據(jù)設(shè)計(jì)書的正確性如何？依據(jù)設(shè)計(jì)出來的系統(tǒng)是否能滿足最終客戶的真正需求。但規(guī)范化的設(shè)計(jì)文檔可以提高溝通效率和溝通的質(zhì)量。

表5 畫面項(xiàng)目設(shè)計(jì)樣例

必須輸入項(xiàng)目名稱畫面顯示位數(shù)新創(chuàng)建編輯參照初始顯示值登錄時(shí)的檢查條件數(shù)據(jù)取得源備注

○擔(dān)當(dāng)者20IIO初期光標(biāo) I：輸入項(xiàng)目

O：輸出項(xiàng)目

3.5 設(shè)計(jì)書的變更管理。由于在軟件項(xiàng)目的開發(fā)過程中，存在許多不可預(yù)料的因素，如：初期用戶的需求不明確，開發(fā)過程中需求不斷地變化。因?yàn)檫@些變更的發(fā)生不可避免，所以對(duì)變更的管理就十分重要。項(xiàng)目的實(shí)踐證明，除了上述要規(guī)范化項(xiàng)目開發(fā)用文檔外，在開發(fā)過程中，在不斷發(fā)生設(shè)計(jì)變更的情況下，要嚴(yán)格保證設(shè)計(jì)文檔與代碼的一致性。

1992年卡內(nèi)基-梅隆大學(xué)的ChristineM.Neuwirth等人，就如何在協(xié)同寫作環(huán)境中發(fā)現(xiàn)和報(bào)告變更的問題，集中討論了三個(gè)方面的問題[2]：（1）應(yīng)該報(bào)告哪些變更？（2）如何表示變更信息？（3）報(bào)告變更信息的界面應(yīng)該如何設(shè)計(jì)？

在已開始編碼后，發(fā)生設(shè)計(jì)書變更時(shí)，設(shè)計(jì)者要評(píng)估所涉及到的DB數(shù)據(jù)表以及相關(guān)畫面的相關(guān)項(xiàng)目，并在設(shè)計(jì)書中明確標(biāo)記出來。首先文檔的履歷中要明記變更履歷，在變更履歷中要明記變更的Sheet頁。在每個(gè)變更的Sheet頁中，所變更的文字要用醒目的顏色例如紅色，或用醒目的背景色。刪掉的文字部分用刪除線，追加的記述要用醒目的文字顏色，同時(shí)變更的文檔本身要發(fā)布版本，放在相關(guān)人員都能看到的地方。此外，最好要有變更管理臺(tái)帳，跟蹤變更的對(duì)應(yīng)情況。最后最重要的是設(shè)計(jì)書的變更與代碼的變更一定要保持一致。始終保證設(shè)計(jì)書的有效性。

4 實(shí)際開發(fā)案件中設(shè)計(jì)書規(guī)范化對(duì)項(xiàng)目影響的分析

如下（圖1）所示，設(shè)計(jì)書書寫的易讀性如何，對(duì)最后項(xiàng)目的整體質(zhì)量有一定的影響。設(shè)計(jì)書書寫的不規(guī)范，可讀性差的話，勢(shì)必在理解設(shè)計(jì)的過程中，花費(fèi)很多時(shí)間去溝通確認(rèn)，此外也容易帶來理解的誤差。分析交付產(chǎn)品后的缺陷來看，其中一定比例的問題原因是設(shè)計(jì)書理解錯(cuò)誤所造成的。

圖1 實(shí)際開發(fā)案件部分影響質(zhì)量因素的分析結(jié)果

5 結(jié)束語

（1）實(shí)踐證明，項(xiàng)目開發(fā)文檔的規(guī)范化及標(biāo)準(zhǔn)化一定程度上可提高項(xiàng)目的成功率及質(zhì)量。（2）項(xiàng)目開發(fā)文檔的規(guī)范化可提高文檔的可讀性，提高溝通的效率。特別是控制變更及其對(duì)應(yīng)文檔的變更，始終保證設(shè)計(jì)書與代碼的一致性，盡管不是保證項(xiàng)目是否能成功的決定條件，但卻是能保證項(xiàng)目成功的必要條件之一。

參考文獻(xiàn)：

[1]陳紹文，精益思想-人，過程和技術(shù)的集成[J].CAD/CAM與制造業(yè)信息化，2002（07）.

[2]胡斌.變更信息管理機(jī)制及其在PDM變更管理中的應(yīng)用[J].中國(guó)全文學(xué)位數(shù)據(jù)庫(kù)，2004.

作者簡(jiǎn)介：晏明（1963.03-），女，遼寧大連人，工程師，工學(xué)碩士，研究方向：軟件工程。

作者單位：大連海事大學(xué)，遼寧大連 116026