What to include, and why



Scott W. Ambler (scott.ambler@ronin-intl.com)
President, Ronin International
5 Oct 2000

  Scott Ambler explains the difference between an essential use case and a
system use case, and offers suggestions on how to document either (with a
focus on the latter). This article is modified from Chapter 3 of The Object
Primer 2nd Edition.
Use cases are one of the most common techniques applied to document the
behavioral requirements for a component-based system. A question that
developers often ask is "What information should you include when
documenting a use case?" Although some of the sections I suggest here are
optional, in my opinion, it is still a good idea to include them. When I am
documenting essential use cases (see also the previous tip Modelling
essential use cases), I have a tendency to leave out the optional sections
(because essential use cases are focused on the what, not the how, and
therefore do not need to be as complex as system use cases). When I am
documenting system use cases, I typically use all sections. To refresh your
memory, the main difference between an essential use case and a system use
case is that, in the system use case, you include high-level implementation
decisions whereas an essential use case captures the intentions of a user in
a technology- and implementation-independent manner.

Two of the sections, actors and included use cases, can actually be
determined by simply looking at your use-case diagram. My experience is,
however, that it is good to have use cases that can stand on their own -- in
other words, use cases that contain all the critical information needed to
understand them and the context they are in. This enables your subject
matter experts (SMEs) to flesh-out use cases individually. (Perhaps they
meet in the mornings to work as a group, and then are assigned use cases to
evolve as far as they can on their own in the afternoon, often increasing
the productivity of the team.)

The sections of a use case


  a.. Name. The name should implicitly express the user's intent or purpose
of the use case, such as "Enroll Student in Seminar."
  b.. Identifier [Optional]. A unique identifier, such as "UC1701," that can
be used in other project artifacts (such as your class model) to refer to
the use case.
  c.. Description. Several sentences summarizing the use case.
  d.. Actors [Optional]. The list of actors associated with the use case.
Although this information is contained in the use case itself, it helps to
increase the understandability of the use case when the diagram is
unavailable.
  e.. Status [Optional]. An indication of the status of the use case,
typically one of: work in progress, ready for review, passed review, or
failed review.
  f.. Frequency. How often this use case is invoked by the actor. This is
often a free-form answer such as once per each user login or once per month.
  g.. Preconditions. A list of the conditions, if any, that must be met
before a use case may be invoked.
  h.. Postconditions. A list of the conditions, if any, that will be true
after the use case finishes successfully.
  i.. Extended use case [Optional]. The use case that this use case extends
(if any). An extend association is a generalization relationship where an
extending use case continues the behavior of a base use case. The extending
use case accomplishes this by inserting additional action sequences into the
base use-case sequence. This is modeled using a use-case association with
the <<extend>> stereotype.
  j.. Included use cases [Optional]. A list of the use cases this one
includes. An include association is a generalization relationship denoting
the inclusion of the behavior described by a use case within another use
case. This is modeled using a use-case association with the <<include>>
stereotype. Also known as a uses or a has-a relationship.
  k.. Assumptions [Optional]. Any important assumptions about the domain
that you have made when writing this use case. At some point you should
verify these assumptions and evolve them either into decisions (see below)
or simply into parts of the basic course or alternate courses of action.
  l.. Basic course of action. The main path of logic an actor follows
through a use case. Often referred to as the happy path or the main path
because it describes how the use case works when everything works as it
normally should.
  m.. Alternate courses of action. The infrequently used paths of logic in a
use case, paths that are the result of an alternate way to work, an
exception, or an error condition.
  n.. Change history [Optional]. Details about when the use case was
modified, why, and by whom.
  o.. Issues [Optional]. A list of issues or action items, if any, that are
related to the development of this use case.
  p.. Decisions. A list of critical decisions, typically made by your SMEs,
pertaining to the content of the use case. It is important to record these
decisions to maintain a group memory.

To make your use case modeling efforts a little easier, I've made a template
that reflects the material described in this tip available for download at
Ronin International Reusable Templates. The template is in Microsoft Word
(and in plain text) format and I hope that you find it, along with the other
templates posted at this page, to be of value.

Resources

  a.. The earlier tip "Modeling essential use cases"


  b.. Building Object Applications That Work: Your Step-By-Step Handbook for
Developing Robust Systems with Object Technology by Scott W. Ambler. New
York: Cambridge University Press, 1998.


  c.. Process Patterns -- Building Large-Scale Systems Using Object
Technology by Scott Ambler. New York: Cambridge University Press, 1998.


  d.. The Object Primer 2nd Edition by Scott W. Ambler. New York: Cambridge
University Press, 2000.


  e.. Software For Use: A Practical Guide to the Models and Methods of
Usage-Centered Design by Larry L. Constantine and Lucy A.D. Lockwood


  f.. Use Case Driven Object Modeling with UML: A Practical Approach by Doug
Rosenberg and Kendall Scott


  g.. The Unified Modeling Language Reference Manual by James Rumbaugh,
Grady Booch, and Ivar Jacobson. Reading, MA: Addison-Wesley Longman, Inc.,
1999.


  h.. Applying Use Cases: A Practical Guide by G. Schneider and J.P. Winters



      About the author
       Scott W. Ambler is President of Ronin International, a consulting
firm specializing in object-oriented software process mentoring,
architectural modeling, and Enterprise JavaBeans (EJB) development. He has
authored or co-authored several books about object-oriented development,
including the recently released The Object Primer 2nd Edition, which covers,
in detail, the subjects summarized in this article. He can be reached at
scott.ambler@ronin-intl.com and at his Web site at www.ambysoft.com.














--
歡迎任何人仕申請開news://nntp.cn/apply