探討為確保軟件外包項目的質(zhì)量如何實現(xiàn)文檔的規(guī)范化

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

關鍵詞：軟件開發(fā)文檔；項目質(zhì)量；Offshore；概要設計；詳細設計；文檔規(guī)范化；軟件開發(fā)文檔標準化

中圖分類號：TP311.5

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

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

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

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

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

2 軟件開發(fā)文檔

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

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

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

概要設計詳細設計單元測試集成測試系統(tǒng)測試軟件交付

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

DB設計說明書 單元測試報告集成測試報告系統(tǒng)測試報告用戶使用指南

3 設計書樣式

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

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

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

表2 數(shù)學表達示例

數(shù)學表達

A≠zero and A≠space

B=0 and C=0

D=zero or D=space

X≦0

日付≧yyyy0401

術語的標準化可提高溝通準確度和效率的同時還能提高書寫詳細設計及測試報告書的文檔質(zhì)量。因為在外包開發(fā)中，不能保證所有參與開發(fā)人員的外語水平很高或在同一個水平上。因此整理術語詞典，供大家查詢與參考是一個很好的方法。

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

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

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

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

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

' 概要

' xxxxx

' 參數(shù)的說明

' ARG1 ： 參數(shù)1

' ARG2 ： 參數(shù)2

' 功能說明

' 使用方法說明

' 返回值

' xx 型

' 補充說明

' xxxxx

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

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

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

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

布爾型（Boolean）blnblnxxx

字節(jié)型（Byte）bytbytxxxData

Collection對象colcolxxx

貨幣類型（Currency）curcurxxx

日期類型（Date）dtmdtmStart

3.4 設計書的構成。以下是設計書的Sheet頁的構成示例（見圖4）。

表4 設計書的樣例

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

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

一個功能的設計書的應盡量集中在一個Excel文檔中表達，這樣可提高查找信息的效率，縮短理解設計書的時間。如果分散在幾個文檔的話，不易查找信息。因為編程是個腦力工作并且側重邏輯思維的過程，理解設計書的過程中如果還需要參照其他文檔的話則思路很容易被打斷。

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

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

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

表5 畫面項目設計樣例

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

○擔當者20IIO初期光標 I：輸入項目

O：輸出項目

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

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

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

4 實際開發(fā)案件中設計書規(guī)范化對項目影響的分析

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

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

5 結束語

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

參考文獻：

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

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

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

作者單位：大連海事大學，遼寧大連 116026