Writing Use Cases

Note the title of this section. We write use cases; we don't draw them. Use cases are not diagrams. Use cases are textual descriptions of behavioral requirements, written from a certain point of view.

"Wait!" you say. "I know UML has use case diagrams, I've seen them."

Yes, UML does have use case diagrams. However, those diagrams tell you nothing at all about the content of the use cases. They are devoid of information about the behavioral requirements that use cases are meant to capture. Use case diagrams in UML capture something else entirely.

A use case is a description of the behavior of a system. That description is written from the point of view of a user who has just told the system to do something in particular. A use case captures the visible sequence of events that a system goes through in response to a single user stimulus.

A visible event is one that the user can see. Use cases do not describe hidden behavior at all. They don't discuss the hidden mechanisms of the system. They describe only those things that a user can see.

Typically, a use case is broken up into two sections. The first is the primary course. Here, we describe how the system responds to the stimulus of the user and assume that nothing goes wrong.

For example, here is a typical use case for a point-of-sale system.

Check Out Item:

1. Cashier swipes product over scanner; scanner reads UPC code.

2. Price and description of item, as well as current subtotal, appear on the display facing the customer. The price and description also appear on the cashier's screen.

3. Price and description are printed on receipt.

4. System emits an audible "acknowledgment" tone to tell the cashier that the UPC code was correctly read.

That's the primary course of a use case! Nothing more complex is necessary. Indeed, even that tiny sequence might be too much detail if the use case isn't going to be implemented for a while. We wouldn't want to record this kind of detail until the use case was within a few days or weeks of being implemented.

How can you estimate a use case if you don't record its detail? You talk to the stakeholders about the detail, without necessarily recording it. This will give you the information you need to give a rough estimate. Why not record the detail if you're going to talk to the stakeholders about it? Because tomorrow, the details are going to change. Won't that change affect the estimate? Yes, but over many use cases, those effects integrate out. Recording the detail too early just isn't cost-effective.

If we aren't going to record the details of the use case just yet, what do we record? How do we know that the use case even exists if we don't write something down? Write the name of the use case. Keep a list of them in a spreadsheet or a word processor document. Better yet, write the name of the use case on an index card, and maintain a stack of use case cards. Fill in the details as they get closer to implementation.

Alternate Courses

Some of those details will concern things that can go wrong. During the conversations with the stakeholders, you'll want to talk over failure scenarios. Later, as it gets closer and closer to the time when the use case will be implemented, you'll want to think through more and more of those alternative courses. They become addenda to the primary course of the use case. They can be written as follows.

UPC Code Not Read:

If the scanner fails to capture the UPC code, the system should emit the "reswipe" tone, telling the cashier to try again. If after three tries the scanner still does not capture the UPC code, the cashier should enter it manually.

No UPC Code:

If the item does not have a UPC code, the cashier should enter the price manually.

These alternative courses are interesting because they hint at other use cases that the stakeholders might not have identified initially. In this case it, appears necessary to be able to enter the UPC or price manually.

What Else?

What about actors, secondary actors, preconditions, post-conditions, and the rest? Don't worry about all that stuff. For the vast majority of the systems you will work on, you won't need to know about all those other things. Should the time come that you need to know more about use cases, you can read Alistair Cockburn's definitive work on the topic.^[1] For now, learn to walk before you learn to run. Get used to writing simple use cases. As you master themdefined as having successfully used them in a projectyou can ever so carefully and parsimoniously adopt some of the more sophisticated techniques. But remember, don't sit and spin.

^[1] [Cockburn2001]