A Book Review
Writing Effective Use Cases by Alistair Cockburn, Addison-Wesley, Boston, 2001, 270 pages,
ISBN 0-201-70225-8, $34.95 paper
"(for a use case) Exactly what am I suppose to write -
how much, how little, and what details?" pg xix
In the field of Software Engineering, Object Oriented Analysis and Design (OOAD) is one method or process for
creating software applications and systems. One of the stages of the OOAD method is to compose scripts on how
the program will be used. The script is known as a "Use Case". Composing a set of use cases is an analysis
of the behaviorial characteristics of the system as it interacts with the users. Hence the name of "use case".
The use case is primarily a prose essay. Like any writing process, determining a message and then stating
it effectively is a very difficult task. Alistair Cockburn's new book, Writing Effective Use Cases,
takes the reader through an extensive discussion of finding the correct message and clearly communicating it.
The book is a comprehensive tutorial on how to write good use cases. I recommend this book as a permanent
addition to your software development library.
The intended audience is the working professional. While not directly stated, the presentation assumes some
working knowledge of use cases and how they fit in the software development process. However, the material
is helpful to all levels of experience. There are many examples from real projects and exercises at the end
of several chapters. Answers to selected exercises are included in an appendix.
I have worked extensively with attorneys and a rule of thumb they use when drafting legal documents is "Add
Detail to Avoid Misinterpretation". Writing Effective Use Cases provides new ideas for adding details to this
software engineering activity I had not previously
considered. I have been using an informal format as described by Ivar Jacobson in Object Oriented Software
Engineering: A Use Case Driven Approach. Mr. Cockburn adds a formal, detailed structure to the use case model
that will improve the quality of my writing.
The topics presented in the book include:
- An extensive discussion of the parts of a use case including design scope, level, actors,
stakeholders, scenarios, extensions, and guarantees.
- A style guide including different presentation formats and sentence structure tips to improve
readability.
- A set of guidelines as a quality control checklist to ensure effective writing.
- A formal method for developing use cases.
- Descriptions on handling specialty situations such as database (CRUD)1 and parameterized use cases,
business process modeling, and including use cases in the Extreme Programming method.
Two detail level guidelines I find immediately useful in my writing are "Use Simple Grammar" and "Who Has the
Ball?". The first guideline improves readability of each action step by limiting the sentence structure to
only one form:
- Subject ... verb ... direct object ... prepositional phrase
By limiting the sentence structure to this simple format the use-case becomes more readable. Its clarity
improves. Clarity is very important because mis-understandings in the early phases of
analysis and design
can lead to problems later on in the coding phase of the process. Correcting such mistakes later on can
be up to 1000 times more expensive than to correct them in the analysis phase.
"Who Has the Ball?", the second guideline, helps clarify the content of each step. The author directs your
attention to the effectiveness of your writing by insisting that at the end of each action step the reader
should clearly ascertain who is the active agent. He uses a soccer metaphor stating that a player may do one
of three things with a soccer ball:
- move it down field;
- pass it to another player; or
- 'clean it'.
In behavioral requirements language these correspond to
- 'perform an action',
- 'request a service from another actor', or
- 'verify a condition',
respectively.
One metaphor from the book I didn't find useful is the striped trousers. He uses this metaphor to show how the main
success scenario is connected to the extensions, or alternative paths through the use case. The success
paths are the stripes on one leg of the trousers and the failure scenarios are the stripes on the other. I
prefer to use a critical path metaphor that linearly connects all paths in a use case. But this is a
personal preference and does not detract from the overall effectiveness of the book.
In conclusion, I highly recommend Writing Effective Use Cases. Mr. Cockburn considers the Use Case Model
to be "an ever unfolding story". To be effective in telling the story, each use case must be a well-written,
prose essay. Mr. Cockburn pulls together in one place a thorough discussion of the many characteristics of
use cases and concludes with guidelines the reader can use for quality control. I will be writing these
guidelines on a crib-card for myself and will add it to my OOAD development forms as a ready reference. I
will also use his formal use case format on my next project.
Below is a template for a use-case provided in the book. The term in bold is the category and the comment in
parentheses provides a description of the content written for that part.
Use Case Template
name: (the name should be the goal to be accomplished in the use-case as a short active verb phrase)
Context of Use: (a longer statement of the goal, if needed.)
Scope: (design scope, what system is being considered black box under design)
Level: (one of: summary, user-goal, subfunction)
Primary Actor: (a role name for the primary actor or description)
Stakeholders and Interests: (list of stakeholders and key interests in the use case)
Precondition: (what we expect is already the state of the world)
Minimal Guarantees: (how the interests are protected under all exits)
Success Guarantees: (the state of the world if goal succeeds)
Trigger: (what starts the use case, may be time event)
Main Success Scenario: (put here the steps of the scenario from trigger to goal delivery and any cleanup after)
- (step #) (action description)
Extensions: (put here any extensions, one at a time, each referring to the step of the main scenario)
- (step altered) (condition): (action or sub use case)
- (step altered) (condition): (action or sub use case)
Technology & Data Variations List: (put here the variations that will cause eventual bifurcation in the scenario)
- (step or variation #): (list of variations)
- (step or variation #): (list of variations)
Related Information: (whatever your project needs for additional information)
Footnotes:
- CRUD is an acronym for Create, Retrieve, Update, and Delete. These are
the four basic operations on a database.
References:
- Cockburn, A., "Goals and Use Cases", JOOP, 10(5), 35-41, Sept. 1997
- Cockburn, A., "Using Goal-Based Use Cases", JOOP, 10(6), 56-62, Nov/Dec. 1997
- Jacobson, I., et al, Object Oriented Software Engineering: A Use Case Driven Approach,
Addison-Wesley, Reading, MA, 1992
- Quatrani, Terry, Visual Modeling with Rational Rose and UML, Addison-Wesley, Reading, MA, 1998
- Schneider, Geri, and Jason P. Winters, Applying Use Cases: A Practical Guide, Addison-Wesley,
Reading, MA, 1998