概要設計文檔編寫規範

在需求明确、準備開始編碼之前，要做概要設計，而詳細設計可能大部分公司沒有做，有做的也大部分是和編碼同步進行，或者在編碼之後。是以，對大部分的公司來說，概要設計文檔是唯一的設計文檔，對後面的開發、測試、實施、維護工作起到關鍵性的影響。

一、問題的提出

　　概要設計寫什麼？概要設計怎麼做？

　　如何判斷設計的子產品是完整的？

　　為什麼說設計階段過于重視業務流程是個誤區？

　　以需求分析文檔還是以概要設計文檔來評估開發工作量、指導開發計劃準确？

　　結構化好還是面向對象好？

　　以上問題的答案請在文章中找。

二、概要設計的目的

　　将軟體系統需求轉換為未來系統的設計；

　　逐漸開發強壯的系統構架；

　　使設計适合于實施環境，為提高性能而進行設計；

　　結構應該被分解為子產品和庫。

三、概要設計的任務

　　制定規範：代碼體系、接口規約、命名規則。這是項目小組今後共同作戰的基礎，有了開發規範和程式子產品之間和項目成員彼此之間的接口規則、方式方法，大家就有了共同的工作語言、共同的工作平台，使整個軟體開發工作可以協調有序地進行。

  總體結構設計：

　　  功能（加工）－>子產品：每個功能用那些子產品實作，保證每個功能都有相應的子產品來實作；

　　  子產品層次結構：某個角度的軟體架構視圖；

　　  子產品間的調用關系：子產品間的接口的總體描述；

　　  子產品間的接口：傳遞的資訊及其結構；

　　  處理方式設計：滿足功能和性能的算法

　　  使用者界面設計；

  資料結構設計：

  　　詳細的資料結構：表、索引、檔案；

　　  算法相關邏輯資料結構及其操作；

　　  上述操作的程式子產品說明（在前台？在背景？用視圖？用過程？······）

　　  接口控制表的資料結構和使用規則

　　  其他性能設計。

四、概要設計寫什麼

  結構化軟體設計說明書結構

　　  任務：目标、環境、需求、局限；

　　  總體設計：處理流程、總體結構與子產品、功能與子產品的關系；

　　  接口設計：總體說明外部使用者、軟、硬體接口；内部子產品間接口（注：接口≈系統界面）

　　  資料結構：邏輯結構、實體結構，與程式結構的關系；

　　  子產品設計：每個子產品“做什麼”、簡要說明“怎麼做”（輸入、輸出、處理邏輯、與其它子產品的接口，與其它系統或硬體的接口），處在什麼邏輯位置、實體位置；

　　  運作設計：運作子產品組合、控制、時間；

　　  出錯設計：出錯資訊、處錯處理；

　　  其他設計：保密、維護；

　　  OO軟體設計說明書結構

  1 概述

  　　系統簡述、軟體設計目标、參考資料、修訂版本記錄

　　  這部分論述整個系統的設計目标，明确地說明哪些功能是系統決定實作而哪些不準備實作的。同時，對于非功能性的需求例如性能、可用性等，亦需提及。需求規格說明書對于這部分的内容來說是很重要的參考，看看其中明确了的功能性以及非功能性的需求。

　　  這部分必須說清楚設計的全貌如何，務必使讀者看後知道将實作的系統有什麼特點和功能。在随後的文檔部分，将解釋設計是怎麼來實作這些的。

  2 術語表

　　  對本文檔中所使用的各種術語進行說明。如果一些術語在需求規格說明書中已經說明過了，此處不用再重複，可以指引讀者參考需求說明。

  3 用例

　　  此處要求系統用用例圖表述（UML），對每個用例（正常處理的情況）要有中文叙述。

  4 設計概述

　　  4.1 簡述

　　　　  這部分要求突出整個設計所采用的方法（是面向對象設計還是結構化設計）、系統的體系結構（例如客戶/伺服器結構）以及使用到的相應技術和工具（例如OMT、Rose）

　　  4.2 系統結構設計

　　　　  這部分要求提供高層系統結構（頂層系統結構、各子系統結構）的描述，使用方框圖來顯示主要的元件及元件間的互動。最好是把邏輯結構同實體結構分離，對前者進行描述。别忘了說明圖中用到的俗語和符号。

 　　 4.3 系統界面

  　　　　各種提供給使用者的界面以及外部系統在此處要予以說明。如果在需求規格說明書中已經對使用者界面有了叙述，此處不用再重複，可以指引讀者參考需求說明。如果系統提供了對其它系統的接口，比如說從其它軟體系統導入/導出資料，必須在此說明。

　　  4.4 限制和假定

　　　　  描述系統設計中最主要的限制，這些是由客戶強制要求并在需求說明書寫明的。說明系統是如何來适應這些限制的。

　　　　  另外如果本系統跟其它外部系統互動或者依賴其它外部系統提供一些功能輔助，那麼系統可能還受到其它的限制。這種情況下，要求清楚地描述與本系統有互動的軟體類型以及這樣導緻的限制。

　　　　  實作的語言和平台也會對系統有限制，同樣在此予以說明。

　　　　  對于因選擇具體的設計實作而導緻對系統的限制，簡要地描述你的想法思路，經過怎麼樣的權衡，為什麼要采取這樣的設計等等。

  5 對象模型

　　  提供整個系統的對象模型，如果模型過大，按照可行的标準把它劃分成小塊，例如可以把用戶端和伺服器端的對象模型分開成兩個圖表述。在其中應該包含所有的系統對象。這些對象都是從了解需求後得到的。要明确哪些應該、哪些不應該被放進圖中。所有對象之間的關聯必須被确定并且必須指明聯系的基數。聚合和繼承關系必須清楚地确定下來。每個圖必須附有簡單的說明。

  6 對象描述

　　  在這個部分叙述每個對象的細節，它的屬性、它的方法。在這之前必須從邏輯上對對象進行組織。你可能需要用結構圖把對象按子系統劃分好。

　　  為每個對象做一個條目。在系統對象模型中簡要的描述它的用途、限制（如隻能有一個執行個體），列出它的屬性和方法。如果對象是存儲在持久的資料容器中，标明它是持久對象，否則說明它是個臨時對象（transient object）。

　　  對每個對象的每個屬性詳細說明：名字、類型，如果屬性不是很直覺或者有限制（例如，每個對象的該屬性必須有一個唯一的值或者值域是有限正整數等）。

　　  對每個對象的每個方法詳細說明：方法名，傳回類型，傳回值，參數，用途以及使用的算法的簡要說明（如果不是特别簡單的話）。如果對變量或者傳回值由什麼假定的話，Pre-conditions和Post-conditions必須在此說明。列出它或者被它調用的方法需要通路或者修改的屬性。最後，提供可以驗證實作方法的測試案例。

  7 動态模型

　　  這部分的作用是描述系統如何響應各種事件。一般使用順序圖和狀态圖。

　　  确定不同的場景（Scenario）是第一步，不需要确定所有可能的場景，但是必須至少要覆寫典型的系統用例。不要自己去想當然地創造場景，通常的政策是描述那些客戶可以感受得到的場景。

  7.1 場景（Scenarios）

　　  對每個場景做一則條目，包括以下内容：

　　　　  場景名：給它一個可以望文生義的名字

　　　　  場景描述：簡要叙述場景是幹什麼的以及發生的動作的順序。

　　　　  順序圖：描述各種事件及事件發生的相對時間順序。

  7.2 狀态圖

　　  這部分的内容包括系統動态模型重要的部分的狀态圖。可能你想為每個對象畫一個狀态圖，但事實上會導緻太多不期望的細節資訊，隻需要确定系統中一些重要的對象并為之提供狀态圖即可。

  8 非功能性需求

  五、概要設計怎麼做

　　  結構化軟體設計方法：

　　　　  詳細閱讀需求規格說明書，了解系統建設目标、業務現狀、現有系統、客戶需求的各功能說明；

　　　　  分析資料流圖，弄清資料流加工的過程；

　　　　  根據資料流圖決定資料處理問題的類型（變換型、事務型、其他型）；

　　　　  通過以上分析，推導出系統的初始結構圖；

　　　　  對初始結構圖進行改進完善：所有的加工都要能對應到相應子產品（子產品的完整性在于他們完成了需求中的所有加工），消除完全相似或局部相似的重複功能（智者察同），理清子產品間的層次、控制關系，減少高扇出結構，随着深度增大扇入，平衡子產品大小。

　　　　  由對資料字典的修改補充完善，導出邏輯資料結構，導出每種資料結構上的操作，這些操作應當屬于某個子產品。

　　　　  确定系統包含哪些應用服務系統、用戶端、資料庫管理系統；

　　　　  确定每個子產品放在哪個應用伺服器或用戶端的哪個目錄、哪個檔案（庫），或是在資料庫内部建立的對象。

　　　　  對每個篩選後的子產品進行清單說明。

　　　　  對邏輯資料結構進行清單說明。

　　　　  根據結構化軟體設計說明書結構對其他需要說明的問題進行補充說明，形成概要設計說明書。

　　  OO軟體設計方法：

　　　　  在OOA基礎上設計對象與類：在問題領域分析（業務模組化和需求分析）之後，開始建立系統構架。

　　　　  第一步是抽取建立領域的概念模型，在UML中表現為建立對象類圖、活動圖和互動圖。對象類就是從對象中經過“察同”找出某組對象之間的共同特征而形成類：

　　　　　　  對象與類的屬性：資料結構；

　　　　　　  對象與類的服務操作：操作的實作算法；

　　　　　　  對象與類的各外部聯系的實作結構；

　　　　　　  設計政策：充分利用現有的類；

　　　　　　  方法：繼承、複用、演化；

　　　　　　  活動圖用于定義工作流，主要說明工作流的5W（Do What、Who Do、When Do、Where Do、Why Do）等問題，互動圖把人員和業務聯系在一起是為了了解互動過程，發現業務工作流中互相互動的各種角色。

　　　　  第二步是建構完善系統結構：對系統進行分解，将大系統分解為若幹子系統，子系統分解為若幹軟體元件，并說明子系統之間的靜态和動态接口，每個子系統可以由用例模型、分析模型、設計模型、測試模型表示。軟體系統結構的兩種方式：層次、塊狀

　　　　  層次結構：系統、子系統、子產品、元件（同一層之間具有獨立性）；

　　　　  塊狀結構：互相之間弱耦合

　　  系統的組成部分：

　　　　  問題論域：業務相關類和對象(OOA的重點)；

　　　　  人機界面：視窗、菜單、按鈕、指令等等；

　　　　  資料管理：資料管理方法、邏輯實體結構、操作對象類；

　　　　  任務管理：任務協調和管理程序；

　　　　  第三步是利用“4＋1”視圖描述系統架構：用例視圖及劇本；說明體系結構的設計視圖；以子產品形式組成包和層包含概要實作模型的實作視圖；說明程序與線程及其架構、配置設定和互相互動關系的過程視圖；說明系統在操作平台上的實體節點和其上的任務配置設定的配置視圖。在RUP中還有可選的資料視圖。

　　　　  第四步是性能優化（速度、資源、記憶體）、模型清晰化、簡單化（簡單就是享受）。

六、概要設計的原則

　　  總體原則和方法：由粗到細的原則，互相結合的原則，定性分析和定量分析相結合的方法，分解和協調的方法和模型化方法。

　　  要系統考慮系統的一般性、關聯性、整體性和層次性。

　　  分解協調：目的是為了創造更好的系統。系統分解是指将一個複雜的系統分解為若幹個子系統，系統協調一是系統内協調，即根據系統的總結構、總功能、總任務和總目标的要求，使各個子系統之間互相協調配合，在各個子系統局部優化基礎上，通過内部平衡的協調控制，實作系統的整體優化；

　　  屏蔽抽象：從簡單的架構開始，隐含細節；

　　  一緻性：統一的規範、統一的标準、統一的檔案模式；

　　  每個子產品應當有一個統一命名的容易了解的名字；

　　  編碼：由外向内（界面－>核心）；

　　  面向使用者：概要設計是對于按鈕按下後系統“怎麼做”的簡要說明；

　　  子產品、元件的充分獨立性、封閉性；

　　  同時考慮靜态結構與動态運作；

　　  每個邏輯對象都應當說明其所處實體對象（非一一對應）；

　　  每個實體對象都有合适的開發人員，并且利于分工與組裝。（詳細說明見本人另一篇文章：系統構架設計應考慮的因素）；

　　  确立每個構架視圖的整體結構：視圖的詳細組織結構、元素的分組以及這些主要分組之間的接口；

　　  軟體構架與使用的技術平台密切相關，目前常用的平台有J2EE、.NET、CORBA等等，是以具體的軟體構架人員應當具備使用這些平台的軟體開發經驗；

　　  通過需求功能與設計子產品之間的清單對應，檢查每個需求功能是否都有相應的子產品來實作，保證需求功能的可追溯性和需求實作（子產品）的完整性，同時可以檢查重複和不必要的子產品。

　　  在需求調研分析過程中對業務處理過程了解的完整性和準确性非常重要。調查了解清楚所有的業務流程才能設計出适合各流程業務節點使用者業務特點和習慣的軟體，使開發出來的軟體更受歡迎。當然在進行軟體概要設計時，要盡量排除業務流程的制約，即把流程中的各項業務結點工作作為獨立的對象，設計成獨立的子產品，充分考慮他們與其他各種業務對象子產品的接口，在流程之間通過業務對象子產品的互相調用實作各種業務，這樣，在業務流程發生有限的變化時（每個業務子產品本身的業務邏輯沒有變的情況下），就能夠比較友善地修改系統程式子產品間的調用關系而實作新的需求。如果這種調用關系被設計成存儲在配置庫的資料字典裡，則連程式代碼都不用修改，隻需修改資料字典裡的子產品調用規則即可。

七、概要設計的重要輸出

　　  編碼規範：資訊形式、接口規約、命名規則；

　　  實體模型：元件圖、配置圖；

　　  不同角度的構架視圖：用例視圖、邏輯視圖、程序視圖、部署視圖、實施視圖、資料視圖（可選）；

　　  系統總體布局：哪些部分組成、各部分在實體上、邏輯上的互相關系；

　　  兩個不可忽視的輸出：

　　　　  與需求功能的關系：對于需求中的每一個功能，用哪一層、哪個子產品、哪個類、哪個對象來實作（一對多關系）；反過來，應當說明将要建立的系統每一層、每個子產品、每個對象、每一個類“做什麼”，他們是為了幫助實作哪些功能（一對多關系）。（需求的顆粒度在一開始往往是比較粗的，是以根據功能點對于整體項目規模的估計或得到項目WBS其誤差範圍也是比較大的。更為重要的原因是，需求往往不是編碼工作分解的準确依據，因為一個需求的功能點可能對應多個代碼子產品，而多個需求的功能點也可能隻對應一個或少數代碼子產品，同時還有軟體複用等因素要考慮，是以隻有在概要設計完成以後才能準确地得到詳細設計或編碼階段的二次WBS，并估計較為準确的整體項目規模。）

　　　　  邏輯與實體位置：每個對象在邏輯上分别落在哪一層、哪個子產品、哪個類；在實體上每個子產品、每個對象、每一個類放在哪個應用伺服器或用戶端的哪個目錄、哪個檔案（庫），或者是建立在資料庫管理系統中的什麼東東（過程、函數、視圖、觸發器等等）。

八、結構化與面向對象方法特點比較

　　  1. 從概念方面看，結構化軟體是功能的集合，通過子產品以及子產品和子產品之間的分層調用關系實作；面向對象軟體是事物的集合，通過對象以及對象和對象之間的通訊聯系實作；

　　  2. 從構成方面看，結構化軟體＝過程＋資料，以過程為中心；面向對象軟體＝（資料＋相應操作）的封裝，以資料為中心；

　　  3. 從運作控制方面看，結構化軟體采用順序處理方式，由過程驅動控制；面向對象軟體采用互動式、并行處理方式，由消息驅動控制；

　　  4. 從開發方面看，結構化方法的工作重點是設計；面向對象方法的工作重點是分析；但是，在結構化方法中，分析階段和設計階段采用了不相吻合的表達方式，需要把在分析階段采用的具有網絡特征的資料流圖轉換為設計階段采用的具有分層特征的結構圖，在面向對象方法中則不存在這一問題。

　　  5. 從應用方面看，相對而言，結構化方法更加适合資料類型比較簡單的數值計算和資料統計管理軟體的開發；面向對象方法更加适合大型複雜的人機互動式軟體和資料統計管理軟體的開發；