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:

  1. An extensive discussion of the parts of a use case including design scope, level, actors, stakeholders, scenarios, extensions, and guarantees.
  2. A style guide including different presentation formats and sentence structure tips to improve readability.
  3. A set of guidelines as a quality control checklist to ensure effective writing.
  4. A formal method for developing use cases.
  5. 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:

  1. move it down field;
  2. pass it to another player; or
  3. 'clean it'.
In behavioral requirements language these correspond to
  1. 'perform an action',
  2. 'request a service from another actor', or
  3. 'verify a condition',

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)

  1. CRUD is an acronym for Create, Retrieve, Update, and Delete. These are the four basic operations on a database.
  • 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

Log in or register to write something here or to contact authors.