Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Use Case Modeling
Guidelines
Version 1.1
Produced by:
Donald Firesmith
3341 Langston Drive
Plano, Texas 75025
(972) 774-4490
Public Domain
 2000 by Donald Firesmith
Page 1
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Revision History
Date
Version
Description
Author
7/27/1999
0.1
Initial draft
Donald Firesmith
10/4/1999
0.2
Inspection draft
Donald Firesmith
1/22/2000
0.3
Updated with input from Chicago CA/RA meeting.
Added list of most common defects.
Donald Firesmith
2/13/2000
0.4
Added guidelines from current projects.
Donald Firesmith
9/27/2000
1.0
Added input from Larry Constantine paper and fixed some
minor defects.
Donald Firesmith
10/15/2000
1.1
Added input from Rebecca Wirfs-Brock’s training
materials
Donald Firesmith
Public Domain
 2000 by Donald Firesmith
Page 2
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Table of Contents
1
INTRODUCTION .....................................................................................................................................4
2
DEFINITIONS ...........................................................................................................................................4
3
USE CASE MODELING GUIDELINES ................................................................................................5
3.1
GENERAL GUIDELINES ............................................................................................................................ 5
3.2
MODELING ACTORS ................................................................................................................................ 8
3.3
MODELING USE CASES.......................................................................................................................... 13
3.4
MODELING USE CASE PATHS ................................................................................................................ 15
4
MOST COMMON DEFECTS ................................................................................................................ 21
5
REFERENCES ........................................................................................................................................ 22
Public Domain
 2000 by Donald Firesmith
Page 3
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
1 Introduction
Over the last decade, use cases have become the most popular de facto standard technique for
software requirements analysis and specification within the object community. However, use
case modeling has numerous well-known problems (see [1], [2], [3], [4], and [5]). It is inherently
more functional than object-oriented, leading to a significant chasm and paradigm shift between
requirements engineering and OO modeling. Putting the use case approach into practice also
often illuminates problems that are not addressed in books and most articles on use cases, and
different requirements engineers typically perform use case modeling differently.
This document provides a hierarchically organized set of detailed guidelines for use case
modeling. These guidelines were collected from numerous real projects during the last six years
and recently refined them using lessons learned while creating the software requirements
specification for a large, embedded, distributed real-time system (the control software for an
automated digital tape library).
2 Definitions
The following terms clarify use case modeling and the following guidelines:

An actor [object or class] (a.k.a., external) is any relevant object or class that is external to a
business, application (whether system or software), or component and interfaces (either
directly or indirectly) with it. Actors either act on the application or are acted on by the
application. Actors can be stereotyped as human roles, data repositories, hardware actors,
and software actors. For example, a digital thermostat system may have only a single actor:
its user. However, the software controlling the digital thermostat may have the following
actors, many of which are internal to the system: actual temperature display, actual
temperature sensor, desired temperature display, decrement actual temperature button,
decrement desired temperature button, increment actual temperature button, increment
desired temperature button, on/off button, status display, and user.

A use case is the specification of a single, complete functional abstraction that captures a
cohesive general way that one or more actors interact with a blackbox business or application
to achieve some goal. A use case is primarily specified in terms of use case paths that capture
these interactions.
Because the goal achieved by the use case almost always benefits a single primary actor, use
cases are typically associated with that actor even if multiple actors are involved. Thus, most
interactions of a use case are largely specified in terms of the primary actor’s intentions and
the system’s corresponding responses.
Note that a use case is not an operation of an actor, but rather is typically that part of the
actors operation (e.g., human actor’s task) that involves the business or application.
Similarly, a use case need not be a business or application operation (function), but rather
may involve multiple functions that are used to achieve the goal.
For example, a simple digital thermostat may have the following use cases: “Change the state
of the digital thermostat”, “Change the desired temperature of the room”, and “Control the
actual temperature of the room”. The customer’s use cases of an Automatic Teller Machine
may include “Deposit money”, “Withdraw money”, “Transfer funds between accounts”, and
“Check balance”.
Public Domain
 2000 by Donald Firesmith
Page 4
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines


Version:
1.0
Version Date: 10/15/2000
An essential use case is a pure requirements-level use case. An essential use case is thus
at a high level of abstraction, technology free, and implementation independent. For
example, an essential use case does not contain any design details that would unnecessary
constrain the human interface.
A use case path (a.k.a., course and RUP scenario) is a contiguous set of referential
relationships traversed by the interactions of the use case. Because a single use case will
typically have an indefinitely large number of paths that traverse it due to branching and
looping, only a minimal basis set of paths is typically identified and analyzed.


A normal path is a use case path that achieves the underlying goal of the use case. For
example, the normal paths through the “Change the desired temperature of the room” use
case may be “Decrement the desired temperature” and “Increment the desired
temperature”.
An exceptional path is a use case path that does not achieve the underlying goal of the
use case. The exceptional paths of the “Control the actual temperature of the room” use
case may include “Handle temperature sensor failure”.

A usage scenario is a single set of contiguous interactions that traverses a use case path.
Whereas a use case is very general and a use case path is more specific, a usage scenario is
totally specific. The large collection of usage scenarios that traverse the same path form an
equivalence class with regard to software testing. For example, the following uniquely
identifies a usage scenario: Increment the desired temperature when the digital thermostat is
in the on state, the current desired temperature is 68°F, and the actual temperature is 69°F.

A use case diagram is a kind of context diagram that documents blackbox use cases, actors,
and the important relationships between them.

A sequence diagram (a.k.a., timing diagram) is a kind of interaction diagram that documents
the dynamic behavior of objects in terms of a sequence of interactions between them.

A blackbox sequence diagram is a sequence diagram that treats the application as a
blackbox interacting with actors. Interactions on blackbox sequence diagrams are
typically specified using narrative English rather than as programming language
messages between internal software objects.
3 Use Case Modeling Guidelines
The following guidelines for performing use case driven requirements analysis and specification, use
case driven scheduling, and use case driven testing have been proven by experience to be costeffective. They fall into the following categories:




General Guidelines
Modeling Actors
Modeling Use Cases
Modeling Use Case Paths
3.1 General Guidelines

Training. Provide initial classroom training for all relevant personnel (requirements
engineers, marketing, domain experts, customers, developers, and testers) who will either
develop, inspect, or read the use case section of the requirements specification. Provide
Public Domain
 2000 by Donald Firesmith
Page 5
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
ongoing on-the-job training for all members of the requirements team including analysts,
domain experts, and testers.
Rationale: Use case modeling is still relatively new to most people. Requirements analysts
who are new to use case modeling tend to produce many defects in the use case model and
resulting requirements specification. Developers, who are used to traditional requirements
specifications, also often have difficulty interpreting and understanding use case-oriented
specifications, especially items intended for others (e.g., the use case categorization that is
used by independent testers to prioritize testing).

Operational requirements only. Use a use case model to analyze and specify the
operational (a.k.a., functional) requirements of an application. Do not use case modeling for
specifying quality requirements (e.g., extensibility, operational availability, portability,
reliability, and reusability).
Rationale: Use cases provide a powerful, industry-standard technique for analyzing and
specifying operational requirements in a user-centered manner.
However, quality
requirements typically cannot be reasonably stated in terms of interactions.
Exception: Business rules and quality requirements may well impact a collection of use cases,
a single use case, or one or more of its paths. Commenting the use case with a relevant
business rule or quality requirement can help clarify from where the operational requirements
of the use case (or path) come.

Document in requirements specification. Document the use case model in the operational
requirements section of the appropriate requirements specification.
Rationale: This places the operational requirements in the context of the other requirements
(e.g., quality requirements, design constraints).

Use standard terminology Use the standard terminology of the application domain (i.e., the
language of the customer and user communities. Avoid the technical jargon of the
development organization. Don't unnecessarily invent new terms. Document the terms in the
Project Glossary.
Rationale: This makes the use case model easier for the customer representatives and domain
experts to understand and review the use case model for correctness.

Use technical writers. Use technical writers to capture and maintain the use case model.
Rationale: Technical writers can ensure consistency of format, conformance to these
guidelines and the associated standard, and provide less expensive updates of text and
diagrams as part of the highly iterative development cycle. Technical writers allow the
requirements engineers and domain experts to concentrate on requirements engineering.

Avoid use case driven design. Do not drive the architecture or design from the structure of
the use cases. Instead, use domain experts and object modeling to identify the key business
abstractions. Use actors and the information passed with the interactions of the use cases to
identify additional classes of objects.
Rationale: Use cases are functional abstractions that are often functionally decomposed.
Thus, use case driven design often results in a functional decomposition design based on godlike controller objects violating the encapsulation of dumb data objects.

Design verification. Verify the object-oriented design against the use case model by tracing
paths through the design.
Public Domain
 2000 by Donald Firesmith
Page 6
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Rationale: The design must implement the requirements captured in the use case model.

Requirements validation. Manually use the use cases to validate the actor descriptions, the
use case paths to validate the use cases, and specific test cases to validate the use case paths.
Perform use case driven testing to validate the implemented application against the use case
model.
Rationale: This guideline ensures the quality of the use case model. Functional test cases
(usage scenarios) can be chosen to exercise use case paths because they capture the
operational requirements

Use an iterative, incremental, parallel development cycle. Iterate the use case model
during the course of development. Develop the use case model in a series of increments
associated with the builds. Develop the use case model in parallel with the rest of
requirements engineering, architecture, design, implementation, integration, and testing.
Define the terms used in the use case model in the project glossary and further elaborate the
business domain concepts in the domain model document.
Rationale: The requirements are never known completely and correctly at the start of
requirements elicitation, analysis, and specification. Domain experts and users are much
better at identifying what is wrong or incomplete with a partial model than specifying it
perfectly up front. The use case model of any nontrivial application is too large to develop
efficiently in a single phase. Incremental development allows the associated application to be
incrementally developed and tested. It also allows for course corrections that insure that the
delivered application is not obsolete as soon as it is released. This guideline results in higher
productivity and user (e.g., designer, tester) satisfaction. Design, coding, and testing against
the use case model will identify defects and holes, resulting in a higher quality.

Schedule later builds by use cases and paths. Although the initial builds should provide a
foundation of core classes that capture an object-oriented architectural framework, later
builds and releases should be scheduled in terms of use cases and paths in the use case model.
Rationale: Schedules based on use cases and use case paths provide incremental value to the
users (actors) and provide testable increments to the independent test team. However,
scheduling all builds on use cases without an overriding architectural vision tends to produce
a functional design that requires significantly more iteration than is necessary.

Standard modeling language. Use a single industry standard modeling language to
document the use case model. Start with UML, but extend it with the latest approved version
of the OPEN Modeling Language (OML).
Rationale: A standard modeling language promotes communication among developers. It
also promotes increased productivity and model quality. This extension of the Unified
Modeling Language (UML) is easier to learn, more expressive and intuitive than vanilla
UML. It also better supports different kinds of actors, relationships between use cases, and
logic.

Choose appropriate tools. During requirements elicitation, use actor cards and use case
cards to initially capture information about actors, use cases, and use case paths. During
requirements analysis, use an upperCASE tool that supports all necessary aspects of the
chosen modeling language to electronically capture the results of use case modeling.
However, do not let the choice of tool drive the choice of modeling language.
Public Domain
 2000 by Donald Firesmith
Page 7
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Rationale: Actor cards and use case cards are appropriate for requirements elicitation, but not
for requirements analysis. This guideline ensures that the tool actually does what is intended.
3.2 Modeling Actors

Clearly differentiate the boundary of the use case model. Decide whether one is modeling
a business, a system application, or a software application. Be consistent when identifying
actors. Label the boundary on relevant diagrams.
Rationale: Unless you clearly distinguish what you are modeling, it will be difficult to
determine what the actors are. Because a system may contain software, hardware, paperware
(documentation), and wetware (personnel), an actor to a software application may be internal
to the larger system.

Initially focus on human actors. Concentrate on identifying human actors before
identifying external applications, systems, databases, etc.
Rationale: This guideline helps identify the most important use cases first.

Initially focus on client actors. Concentrate on identifying actors that depend on the
application rather than supporting server actors on which the application depends. Identify
the client actors, which make requests of the application, which notify the application about
events, and which proactively provide information to the application.
Rationale: This guideline helps identify the most important actors and use cases first.

Actors should be cohesive. Actors should have a cohesive set of goals and responsibilities.
Every actor should not involve every use case. Client actors typically benefit from more than
one use case, but do not benefit from more than 10-15 use cases. Server actors need not
benefit from any use case. No actor typically benefits from every use case. Use inheritance
to factor out common actor characteristics.
Rationale: This guideline makes actors and their resulting use cases easier to understand.

Identify actor stereotypes. Differentiate the different stereotypes of actors with intuitive
icons.
Rationale: This guideline makes context diagrams and use case diagrams easier to understand
and avoids confusion (e.g., when the UML stick figure is used for hardware and software
actors as well as human actors).

Specify roles rather than people or job descriptions.
Rationale: Remember that human actors are roles, not persons or job titles. A single person
may play multiple roles when interacting with an application.

Properly name the actors. Provide a unique, meaningful name to each actor. The name
should be consistent with, and implied by, the associated definition and responsibilities.
Name human actors after the associated roles that people play when interacting with the
application. Use the common name for legacy applications and systems. Watch out for
unintended synonyms due to parallel development.
Rationale: Remember that the name of a human actor need not be a job title, because the
same person may play multiple roles when interacting with the application.
Bad Example: Button pusher. (What the user of a digital thermostat does, not who the actor
is.)
Public Domain
 2000 by Donald Firesmith
Page 8
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Better Example: User

Define the actors. Provide a clear, concise, glossary definition of each actor that is
consistent with the name of the actor and its responsibilities.
Rationale: Because actors need not be job titles, they may be new concepts, even to domain
experts.
Because domain experts and requirements analysts often have different
undocumented definitions for the same terms, formally defining the actors helps avoid
confusion.
Bad Example: The user is the person who presses the buttons on the digital thermostat.
Good Example: The user is the actor who uses the digital thermostat to control the
temperature of a room.

Document actor responsibilities. Document the responsibilities of each actor. Where
appropriate, include responsibilities for doing, knowing, and enforcing business rules.
Document responsibilities rather than specific tasks or operations that implement the
responsibilities.
Rationale: An actor is largely defined in terms of its responsibilities. Documenting the
responsibilities provides the context needed to understand and justify the associated use
cases. An actor should have a cohesive set of responsibilities.
Bad Example: The following “responsibilities” of the user of a digital thermostat are at too
low of a level of detail:




Turn on the digital thermostat.
Turn off the digital thermostat
Decrement the desired temperature of the room.
Increment the desired temperature of the room.
Good Example: The following responsibilities are above the level of abstraction of an
operation:

Control the actual temperature of the room by:




Observing the display.
Changing the state of the digital thermostat.
Changing the desired temperature of the room.
Document actor state behavior. Document the state machines of any actors.
Rationale: This guideline clarifies use case path preconditions and postconditions.
Example: The air conditioner, fan, and furnace have the following state model:
Public Domain
 2000 by Donald Firesmith
Page 9
Donald Firesmith
Version:
Document ID: UCMG
Use Case Modeling Guidelines
1.0
Version Date: 10/15/2000
Air Con dition er
Fu nctio ning
On
tu rnOff
Off
tu rnOn
hardwar eFailu re
Malfunctionin g

Do not specify requirements on actors.
Rationale: The use case model specifies requirements on the blackbox business or application
rather than the actors with which it interacts.
Bad Example: The user shall control the temperature of the digital thermostat.
Good Example: The digital thermostat shall permit the user to set the desired temperature of
the digital thermostat to any temperature between the minimum and maximum desired
temperatures.

Document required actor expertise. Specify the required expertise and training for all
human actors.
Rationale: Different users of an application require different levels of training and expertise.
By specifying the required levels, training plans can be developed.
Example: An average six year old should be able to successfully use the digital thermostat
with minimal (i.e., 5 minutes of) training.

Organize by actors. Organize the use case model into packages, first by actor stereotype
(e.g., human role, hardware, software) and then by specific actor (e.g., customer, user).
Within a package, use a standard sort order, either alphabetically or by major system
function. Those subordinate use cases that are not primarily associated with any one actor
should be grouped into a package associated with the application.
Rationale: This guideline provides a natural organization to the use case model that is both
easy to use and user-centric. Most use cases primarily benefit one actor.

Summarize the context. Use one or more context diagrams to summarize the static
environment of the application in terms of its actors and the relationships between it and its
actors. Also, document all significant relationships between actors on the context diagram.
Provide narrative English description of the context diagram that clarifies anything that is not
totally obvious. Also, summarize the workflow between actors.
Public Domain
 2000 by Donald Firesmith
Page 10
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Rationale: Context diagrams help one understand the context of an application. Relationships
between actors often make the resulting context more understandable, especially inheritance
relationships or associations when the order of use cases depends on interactions between
actors. This guideline makes it easier for domain experts and others less familiar with this
diagram to understand it. The overall goals of the business or application are implemented by
workflows that often involve multiple actors and use cases.
Example: The following is an example system context diagram:
User
controls
the actual temperature
of the room
using the
Digital
Thermostat
controls
the actual temperature
of the
Room
Public Domain
 2000 by Donald Firesmith
Page 11
Donald Firesmith
Version:
Document ID: UCMG
Use Case Modeling Guidelines
1.0
Version Date: 10/15/2000
Example: The following is an example software context diagram:
User
presses
the
On
Off
Button
interrupts
the
presses
the
presses
the
Decrement
Temperature
Button
Incr ement
Temperature
Button
interrupts
the
interrupts
the
Digital
Thermostat
Software
Integrated
Circuit
reads sensors
via the
controls hardware
via the
Multiplexing
Digital to Analog
Converter
Analog to Digital
Converter
displays information
to the user
via the
reads the
controls
the
controls
the
controls
the
Temperature
Sensor
Air
Conditioner
Fan
Furnace
measur es
the actual temperatur e
of the
cools
the
blows
conditioned air
through the
observes
the
Display
heats
the
Room

Specify interfaces to actors. Specify any required interfaces to actors, especially to existing
hardware devices and software applications in the external API specification.
Rationale: This guideline ensures that the designers have adequate requirements to implement
the interface across which the interactions flow.
Public Domain
 2000 by Donald Firesmith
Page 12
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines

Version:
1.0
Version Date: 10/15/2000
Document all relevant actors. Document both actors that directly interface with the
application as well as actors that indirectly interface via other actors.
Rationale: The object model often includes classes corresponding to both indirect actors and
direct actors. Direct actors (e.g., keyboard, console) are sometimes less important than the
indirect human actors that use them.
3.3 Modeling Use Cases

Use cases should be functionally cohesive. Each use case should fulfil all related business
or application responsibilities involved in the primary actor’s goal. Do not base use cases on
GUI screens.
Rationale: This guideline makes use cases easier to understand.

Properly name the use cases. Name each use case with a unique, unambiguous, meaningful
active verb phrase that captures the goal of the primary actor. Name the use cases from the
actor’s viewpoint rather than the system viewpoint. Optionally, include the name of the
primary actor that benefits from the use case.
Rationale: Verb phrases are best because use cases are functional abstractions, and active
verb phrases increase understandability. Adding the actor's name makes it easier to
understand who benefits from the use case.
Bad Examples:


Turn on the digital thermostat. (This is really a use case path)
Desired temperature is changed. (This is not an active verb phrase and is from the wrong
viewpoint.)

Temperature Control. (This is not a verb phrase and is from the wrong viewpoint.)
Good Examples:



Toggle the state of the digital thermostat between on and off.
User changes desired room temperature.
Specify use case requirements. Provide a uniquely identified, textual requirement for each
use case that captures its functional abstraction and actor’s goal.
Rationale: This guideline provides an overview of the use case. A textual requirement is also
the information expected by domain experts who are used to textual requirements
specifications. This guideline also supports the creation of an executive requirements
summary document containing only the names and primary requirements of use cases and
their paths.
Bad Examples:


The user changes the desired temperature of the room. (This is not a requirement, but
rather an observation.)
The user shall change the desired temperature of the room. (This constrains the user. It
is not a requirement on the digital thermostat).
Public Domain
 2000 by Donald Firesmith
Page 13
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Good Examples:


The digital thermostat software shall permit the user to change the desired temperature of
the room. (Written as a requirement - “shall” - on the digital thermostat.)
Create use case diagrams. Create a top-level use case diagram for each primary actor that
summarizes the behavioral context of the application in terms of the primary actor’s use
cases, any related actors, and the important relationships between them. Optionally create a
lower-level use case diagram for each use case that has numerous relationships to other use
cases. Identify the primary actor associated with each use case on the use case diagram.
Provide narrative English descriptions of the use case diagrams that clarify anything that is
not totally obvious in the diagram. Also, document the boundaries of the blackbox application
on each use case diagram, and label the scope of each diagram.
Rationale: Applications often have too many actors and use cases to document on a single
top-level use case diagram. By limiting the scope of the diagram, the diagram becomes
simpler, more focused, and therefore easier to understand. The diagrams also become easier
to maintain because the impact of changes is more localized.
Warning: Do not waste significant time debating the relationships (e.g., invokes, extends,
inherits) between use cases. If the relationship is unclear, do not label it. The distinction
between relationship types is often unclear and the subject of many unnecessary arguments.
The extends relationship is typically quite confusing to readers and should be avoided on
most projects. The extends relationship should also not be misused to represent what is really
the distinction between normal and exceptional paths through a single use case.

Provide a business context. Use an activity diagram to optionally document the larger
business context of the use case.
Rationale: A user may perform multiple use cases in order to achieve an overall goal. This
guideline helps the reader understand the overall work flow to which the use case contributes.
For example, a user of an ATM machine may first check the balances in several accounts
before deciding from which account to withdraw funds. This guideline is optional because
the individual goals of many use cases are identical with the overall business context of the
use case.

Annotate business rules. Optionally note the business rules or policies (e.g., quality
requirements) that impact a use case or its paths.
Rationale: Although use cases themselves are not intended to capture quality requirements,
providing a link to them makes it easier to see from where the operational requirements of the
use case and its path come.

Provide a business justification. Document the business justification for each use case.
Ensure that the business justification actually justifies the use case and is more than merely a
restatement of the use case requirement.
Rationale: This guideline ensures that the use case specifies a real requirement.

Use essential use cases. Use essential (i.e., requirements analysis level) use cases to specify
the actor’s goal or intent (i.e., the “what,” not the “how”). Avoid unnecessarily specifying
architecture or design decisions in use cases. Use preconditions rather than screen navigation
details.
Rationale: By including design information in use case models, the distinction between
requirements and design is blurred. Design-level use cases require more maintenance
Public Domain
 2000 by Donald Firesmith
Page 14
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
because they must be updated each time the design changes. Being technology free, essential
use cases are more robust when technology changes. Design-level use cases can lead to more
traditional user interfaces that unnecessarily constrain the creativity of user interface
designers.
Bad Examples (system boundary):


The user presses the on-off button on the panel of the digital thermostat.
The user presses the soft button corresponding to the requested an account type on the
touch screen of the automatic teller machine.
Good Examples (system boundary):


The user requests a change of state by the application.
The user requests the desired account type from the ATM.
3.4 Modeling Use Case Paths

Only specify basis paths. Only specify a minimal set of normal and exceptional basis paths
through the use case. Follow the Structured Testing approach to finding basis paths, the
number of which is equal to the McCabe’s cyclometric complexity of the potential
interactions of the actors and the blackbox business, application, or component. Similarly, do
not try to model every conceivable exceptional path, but only those paths that are significant
and that may reasonably be expected to occur.
Rationale: This guideline limits the amount of use case modeling work to a practical level.
Branching and looping that is visible at the interface can produce an indefinitely large
number of paths.

Individually specify paths. Do not use branching and looping to combine multiple paths
into a single use case path specification.
Rationale: Combining multiple paths into a single specification makes the paths more
complex, makes it difficult to write common preconditions and postconditions, and makes it
more difficult to use the paths to generate associated test cases.

Properly name the use case paths. Name each use case path with a unique, unambiguous,
meaningful phrase that captures the essence of the path. The name should be consistent with,
and implied by, the associated requirement, preconditions, interactions, and postconditions.
Rationale: This guideline improves communication by improving understandability.
Bad Example:

Control the actual temperature of the room fails. (May fail multiple ways.)
Good Example:


Handle temperature sensor failure.
Specify use case path requirements. Provide a uniquely identified, unambiguous textual
requirement for each use case path that captures its functional abstraction, preconditions, and
postconditions.
Rationale: This guideline provides an overview of the use case path, it easier to understand.
This guideline also promotes the testability of the resulting implementation. A textual
requirement is also the information expected by domain experts who are used to textual
Public Domain
 2000 by Donald Firesmith
Page 15
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
requirements specifications. This guideline also supports the creation of an executive
requirements summary document containing only the names and primary requirements of use
cases and their paths.
Bad Examples:


The user successfully increments the desired temperature of the room. (Not written as a
requirement.)
The user shall be able to increment the desired temperature. (Vague – temperature of
what. Written as a requirement on the user, not the digital thermostat.)

The digital thermostat shall allow the user to increment the desired temperature of the
room. (This is too general for a path – does not say under which preconditions it holds.)
Good Example:


The digital thermostat shall allow the user to increment the desired temperature of the
room when the desired temperature is less than the maximum desired temperature.
Document relevant assertions. For each use case path, document both its preconditions and
postconditions. Use assertions to capture required information formats and validation rules
when interfacing with human actors, but use the external API specification to capture API
formats and validation rules. Use preconditions to avoid specifying screen navigation details.
If the assertions depend on the state of some object, then use state modeling to capture this
information.
Rationale: Without preconditions, there is no way to determine what is required to execute
the path successfully. Without postconditions, there is no guarantee that the execution was
correct, even if the visible interactions were correct. Postconditions can be used to specify
otherwise hidden internal constraints. Notice that preconditions and postconditions are thus
path-specific and should therefore not be documented at the use case level. This greatly helps
with the specification of the associated test cases.
Examples:


Preconditions of the “Increment desired temperature” normal path of the “Change the
desired temperature” use case include:



The desired temperature is below the maximum.
The display is functioning.
Postconditions of the “Increment desired temperature” normal path of the “Change the
desired temperature” use case are requirements and include:




The digital thermostat is in the on state.
The digital thermostat shall be in the on state.
The digital thermostat shall store the new desired temperature, which shall be one
degree larger than the old desired temperature.
The display shall display the new desired temperature.
Document the interactions. Completely document each interaction between the application
and actors including the client and server of the interaction, the interaction itself, and any
information that flows with the interaction. Use narrative English sentences that incorporate
Public Domain
 2000 by Donald Firesmith
Page 16
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
the vocabulary of the user or application domain, while avoiding the use of software
engineering technical jargon. Document interactions initiated by actors in terms of the
intention of the actor. Document interactions initiated by the application in terms of its
requirements. Optionally document interactions between the actors, but only if it helps one
understand the purpose of the interactions. Ensure that each interaction is actually an
interaction and not really a precondition, postcondition, or traditional textual functional
requirement or hidden calculation.
Rationale: It is important to know which is the client and which is the server in order to
determine who provides the resulting service. In addition, only the interactions initiated by
the application represent requirements. The specification is incomplete if it does not specify
what information is passed with the interaction, and this information helps to identify classes
in the corresponding object model. The interactions are confusing and hard to understand if
preconditions, postconditions, and traditional textual functional requirements are incorrectly
labeled as interactions.
Bad Examples:



The user presses the on/off button. (Not part of the increment desired temperature path.
Use a precondition instead.)
The digital thermostat shall increment its desired temperature. (Actually, a postcondition
on internal data that technically is not visible at the interface.)
The desired temperature display displays the new desired temperature.
postcondition that contains a design constraint.)
(Actually a

The digital thermostat software shall display the desired temperature. (Not specified as
an interaction. What is the actor?)
Good Examples:

System requirements (assuming system boundary):



Within .1 second of the user request to increment the desired temperature, the digital
thermostat system shall notify the user of the incremented desired temperature.
Software requirements (assuming system architecture complete and software boundary):




The user requests the desired temperature to be incremented by the system.
The user presses the increment desired temperature button.
The increment temperature button interrupts the digital thermostat software with the
string “increment desired temperature”.
Within .1 second of the user pressing the increment desired temperature button, the
digital thermostat software shall request the display to display the desired
temperature of the room as a 1 to 3 digit integer followed by either “°F” or “°C”.
Capture exceptional paths and interactions. Specify the exceptional basis paths as well as
the normal paths through a use case. Also document exceptional interactions as well as
normal interactions, but avoid analysis paralysis due to trying to cover too many, extremely
unlikely exceptional paths.
Rationale: Too often, requirements only specify how an application must function under
normal circumstances, but not how it should function during abnormal circumstances.
Public Domain
 2000 by Donald Firesmith
Page 17
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Requirements are therefore incomplete if only normal paths are specified. Exception handling
software can often make up to 80% of business-critical or safety-critical software needing
high operational availability and reliability. Unless exceptional paths are specified, there is
little likelihood that they will be implemented or implemented correctly, and exceptional
interactions must be documented if exceptional paths are to be completely documented.
Testing exceptional paths and interaction is most likely to find defects. This guideline is
critical if the resulting application is to be robust or have high operational availability.
Example path:

Handle temperature sensor failure.
Example interaction:

The digital thermostat software shall notify the user when the temperature sensor fails.

Categorize the paths. Categorize each use case path with its stability (how likely is it to
change), frequency (how often does it execute), criticality (how important it is to the user),
probability of defects (how likely are the developers to implement it correctly), and the
resulting risk. Use values of high, medium, and low. Calculate risk as a function of stability,
frequency, criticality, and probability of defects.
Rationale: The implementation of unstable paths may be postponed until the paths solidify, or
else implementation may be moved forward in the schedule so that early prototyping may
stabilize them. Reliability may be improved if limited test resources are allocated to paths
that are executed frequently. Testers can emphasize the paths, the correct execution of which
is critical to the user. Testing resources should also be allocated to those paths most likely to
contain defects due to complexity or uncertainty (e.g., exceptional paths). This guideline
allows one to identify the risk associated with each path in order to prioritize the scheduling
of the development and testing of each path.

Factor out common interactions. Use subordinate use case paths and the “invokes”
relationship to factor out common cohesive sets of interactions. However, watch out for
excessive functional decomposition of the use cases. Do this relatively late during use case
modeling when the common interactions are known.
Rationale: This guideline simplifies the interactions and improves maintainability by
eliminating unnecessary redundancy.
Example interaction:


Perform use case path foo.
Document the logic. Where appropriate, document the logic of the use case (e.g., branching
or optional interactions, looping, flexible orderings, and critical regions1) using pseudocode
in the interactions and using logic boxes on sequence diagrams. However, branching can be
ignored if interactions and sequence diagrams are documented one per path.
Rationale: This clarifies the actual behavior of the interactions. Often blocks of interactions
can be performed in any order. Noting that the order of sets of blocks of interactions is
undefined eliminates unnecessary workflow constraints on the human interface.
1
A critical region is a block of interactions that must be performed to completion without
interruption.
Public Domain
 2000 by Donald Firesmith
Page 18
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
Example pseudocode:






If condition-foo holds, perform the following block of interactions (branching )
Repeat the following block of interactions until condition-foo holds (looping)
While condition-foo, repeat the following block of interactions (looping)
The following two blocks of interactions can be performed in any order (flexible
ordering)
The following block of interactions must be performed without interruption (critical
region)
Create sequence diagrams. Use blackbox sequence diagrams on whiteboards to informally
analyze path interactions. Include blackbox sequence diagrams to formally document
complex paths containing complex logic.
Rationale: Complex interactions are easier for most readers to understand if they are
documented graphically.
Exception: Sequence diagrams contain information that is redundant with the textual
interactions, which provide more information than the diagrams. Except for complex paths
that require diagrams to improve understandability, one may wish to only temporarily create
sequence diagrams on whiteboards during initial analysis and not maintain them in the
documentation.

Some interactions are requirements. Formally specify those interactions that are initiated
by the business or application as requirements using the standard terminology of
requirements (e.g., the use of the term “shall”).
Avoid unnecessary design constraints. For example, do not explicitly mention screen names
or the closing of screens. Instead of specifying screen navigation, leave these as design
decisions documented in the human interface design document.
Uniquely identify each such requirement including each item in the list of information passed
with the interaction.
Rationale: Any interaction initiated by the application is visible behavior and therefore
required. Uniquely identifying requirements supports traceability.
Exception: Uniquely identifying requirements clutters up the requirements, making them less
readable. A requirements management tool may automatically provide unique identifiers that
can be turned off in the paper requriements specifications.
Bad Examples:

The user shall press the increment desired temperature button.
constrains an actor.)
(This improperly

The digital thermostat displays the new desired temperature to the user. (Not written as a
requirement.)
Good Example:

The digital thermostat shall notify the new desired temperature to the user.
Public Domain
 2000 by Donald Firesmith
Page 19
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines

Version:
1.0
Version Date: 10/15/2000
Postconditions are requirements. Document each postcondition as a requirement using the
standard format for requirements (e.g., the use of the term “shall”). Uniquely identify each
postcondition.
Rationale: A postcondition of the application is a required outcome of a use case path.
Uniquely identifying requirements supports traceability.
Exception: Uniquely identifying requirements clutters up the requirements, making them less
readable. A requirements management tool may automatically provide unique identifiers that
can be turned off in the paper requriements specifications.
Bad Example of postconditions of the “Decrement desired temperature” normal path of the
“Change the desired temperature” use case include:


The desired temperature shall be decremented. (Merely repeats the use case name.)
The new desired temperature is one degree less than the old desired temperature. (Not
written as a requirement.)
Good Examples of postconditions of the same path:



The digital thermostat shall store the new desired temperature, which shall be one degree
less than the old desired temperature.
Specify complex internal algorithms. If a new value is the result of a complex calculation
that occurs internally to the blackbox application, use a postcondition to explicitly specify the
complex algorithm to be used to calculate the new value.
Rationale: Because the interactions only specify visible interactions between the application
and its actors, they are not appropriate for specifying the complex algorithms sometimes
needed to calculate a post-execution value.
Example:


The digital thermostat shall be in the on state.
The new account balance equals the function foo() of its original value.
Standardize interaction formats. Use a standard format to document interactions. For
example, interactions may be stereotyped as requests, responses, and event notifications. Use
a technical writer to ensure compliance with the standard formats.
Rationale: This guideline greatly increases understandability and maintainability by avoiding
insignificant differences that may confuse the reader.
Example formats:

Actor ‘A’ sends a ‘B’ request to ‘the application,’ which includes the following
information: X, Y, and Z.

‘The application’ shall send an ‘A’ response to actor ‘B’, which includes the following
information: X, Y, and Z.

‘The application’ shall send an ‘A’ event notification to actor ‘B’, which includes the
following information: X, Y, and Z.
Public Domain
 2000 by Donald Firesmith
Page 20
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
4 Most Common Defects
The most common defects to avoid when performing use case modeling are:
1. Use case path specifications that include unnecessary design constraints (e.g., screen
navigation, user interface mechanism).
2. Use case path specifications that confuse preconditions, interactions, and postconditions (e.g.,
listing preconditions and postconditions as interactions).
3. Use case path specifications that do not document interactions as interactions between an
actor and the blackbox system. In other words, an interaction should identify the actor, the
system, the interaction, the party that initiated the interaction, and the required information
that must flow with the interaction.
4. Use case path specifications that only specify interactions initiated by actors (i.e., that do not
specify system responses or interactions initiated by the system).
5. Use case specifications that only specify normal paths (i.e., forgetting to specify exceptional
paths).
6. Use case specifications that have an inconsistent system boundary so that the actors are
inconsistently identified. The boundary should be the business, the system, or the software.
7. Use case specifications that specify interactions as if they were software messages. Instead,
use active voice narrative English rather than message signatures. Use the terminology of the
domain rather than software engineering jargon. Document user initiated interactions in
terms of user intent rather than in terms of user interface mechanism. Specify format, syntax,
and semantics of interactions with non-human actors in the External API Specification.
Public Domain
 2000 by Donald Firesmith
Page 21
Donald Firesmith
Document ID: UCMG
Use Case Modeling Guidelines
Version:
1.0
Version Date: 10/15/2000
5 References
[1] Donald G. Firesmith, “Use Cases: The Pros and Cons,” in Wisdom of the Gurus: A Vision for Object Technology,
Charles F. Bowman, ed., SIGS Books Inc., New York, New York, 1996, pp. 171-180.
[2] Alistair Cockburn, “Structuring Use Cases with Goals,” Journal of Object-Oriented Programming, SIGS Publications,
Sep-Oct 1997 and Nov-Dec 1997.
[3] Tim Korson, “The Misuse of Use Cases,” Object Magazine, 8(3), SIGS Publications, 1998, pp. 18-20.
[4] Susan Lilly, “Use Case Pitfalls: Top 10 Problems from Real Projects, in the Proceedings of TOOLS USA’99.
[5] Rebecca Wirfs-Brock, Writing Use Cases, Scenarios, and Conversations, Wirfs-Brock Associates, 15 May 2000.
Public Domain
 2000 by Donald Firesmith
Page 22