編寫用例文檔-文檔中應包括哪些部分，為什么要包括這些部分

Scott Ambler 闡明了基本用例和系統用例之間的區別，并針對如何編寫這兩類用例的文檔提出了一些建議（主要討論系統用例）。本文由《The Object Primer 2^nd Edition》的第三章改編而來。

當記錄基于組件的系統的行為需求時，用例是最常用的技術之一。開發人員常問的一個問題是，“用例文檔應該包括哪些信息？”盡管我在此提到的一些部分是可選的，但在我看來，將這些部分包括在用例文檔中不失為一個好主意。當編寫基本用例的文檔時（另請參閱前一篇技巧 Modelling essential use cases），我傾向于略去可選部分（因為基本用例關注的是是什么，而不是為什么，因此不必像系統用例那樣復雜）。當編寫系統用例時，我通常將所有部分都包括在內�；仡櫼幌�，基本用例和系統用例之間的主要區別是，系統用例包括了高級實現決策，而基本用例是要以與技術和實現無關的方式捕捉用戶的意圖。

參與者 (actor) 和被包含的用例這兩個部分實際上只看用例圖即可確定。但是，按我的經驗，各個用例最好相互獨立 — 換句話說，用例應該包含理解它們所需的全部關鍵信息以及它們所在的上下文。這使您的主題問題專家 (SME) 能夠分別充實各個用例。（他們可能上午以小組為單位協同工作，下午則各自獨立地以最快的速度充實所分配的用例，從而提高了整個小組的生產效率。）

• 名稱。名稱無疑應該表明用戶的意圖或用例的用途，如“研究班招生”。
• 標識符 [可選]。唯一標識符，如 "UC1701"，在項目的其他元素（如類模型）中可用它來引用這個用例。
• 說明。概述用例的幾句話。
• 參與者 [可選]。與此用例相關的參與者列表。盡管這則信息包含在用例本身中，但在沒有用例圖時，它有助于增加對該用例的理解。
• 狀態 [可選]。指示用例的狀態，通常為以下幾種之一：進行中、等待審查、通過審查或未通過審查。
• 頻率。參與者訪問此用例的頻率。這是一個自由式問題，如用戶每次錄訪問一次或每月一次。
• 前置條件。一個條件列表，如果其中包含條件，則這些條件必須在訪問用例之前得到滿足。
• 后置條件。一個條件列表，如果其中包含條件，則這些條件將在用例成功完成以后得到滿足。
• 被擴展的用例 [可選]。此用例所擴展的用例（如果存在）。擴展關聯是一種廣義關系，其中擴展用例接續基用例的行為。這是通過擴展用例向基用例的操作序列中插入附加的操作序列來實現的。這總是使用帶有 <<extend>> 的用例關聯來建模的。
• 被包含的用例 [可選]。此用例所包含用例的列表。包含關聯是一種廣義關系，它表明對處于另一個用例之中的用例所描述的行為的包含關系。這總是使用帶有 <<include>> 的用例關聯來建模的。也稱為使用或具有 (has-a) 關系。
• 假設 [可選]。對編寫此用例時所創建的域的任何重要假設。您應該在一定的時候檢驗這些假設，或者將它們變為決策的一部分（請參閱usecase/index.shtml#decisions">下文），或者將它們添加到操作的基本流程或可選流程中。
• 基本操作流程。參與者在用例中所遵循的主邏輯路徑。因為它描述了當各項工作都正常進行時用例的工作方式，所以通常稱其為適當路徑 (happy path) 或主路徑 (main path) 。
• 可選操作流程。用例中很少使用的邏輯路徑，那些在變更工作方式、出現異�；虬l生錯誤的情況下所遵循的路徑。
• 修改歷史記錄 [可選]。關于用例的修改時間、修改原因和修改人的詳細信息。
• 問題 [可選]。如果存在，則為與此用例的開發相關的問題或操作項目的列表。
• 決策。關鍵決策的列表，這些決策通常由您的 SME 作出，并屬于用例的內容。將這些決策記錄下來對于維護團體記憶庫 (group memory) 是相當重要的。

  為了讓用例建模工作變得輕松一點，我制作了一個模板，它反映了本技巧說明的內容，可通過以下鏈接下載這個模板：Ronin International Reusable Templates。此模板是以 Microsoft Word（和純文本）格式提供的，我希望此模板以及該網頁上的其他模板對您能有所用處。

• 以前的技巧："Modeling essential use cases"
• 《Building Object Applications That Work: Your Step-By-Step Handbook for Developing Robust Systems with Object Technology》，Scott W. Ambler 著。紐約：Cambridge University 出版社，1998 年。
• 《Process Patterns -- Building Large-Scale Systems Using Object Technology》，Scott Ambler 著。紐約：Cambridge University 出版社，1998 年。
• 《The Object Primer 2nd Edition》，Scott W. Ambler 著。紐約：Cambridge University 出版社，2000 年。
• 《Software For Use: A Practical Guide to the Models and Methods of Usage-Centered Design》，Larry L. Constantine 和 Lucy A.D. Lockwood 著
• 《Use Case Driven Object Modeling with UML: A Practical Approach》，Doug Rosenberg 和 Kendall Scott 著
• 《The Unified Modeling Language Reference Manual》，James Rumbaugh、Grady Booch 和 Ivar Jacobson 著。Reading，MA：Addison-Wesley Longman 公司，1999 年。
• 《Applying Use Cases: A Practical Guide》，G. Schneider 和 J.P. Winters 著