Use Cases

Analysis starts with a question that has nothing to do with classes: who wants what from this system, and what has to happen for them to get it? A use case answers it for one goal, as a short story with a happy path and the ways it can go wrong. Use cases come before the domain model (chapter 4) because the concepts you need are the ones the stories mention, and they come before any class design because you cannot decide who is responsible for something nobody has described.

The Words

Two points that prevent most confusion. Roles, not people: a person can play both Member and Librarian (a librarian borrowing a book); the use case cares about the role. Scope decides who is an actor: inside the lending system the librarian is an actor, because the system is the software. If your scope were "the library as an organisation", the librarian would be inside the boundary. Always state the scope.

Finding Actors and Goals

A reliable method is to list actors first and then ask each one the same question: what do you want to get done with this system? Ask "what else?" until the answers dry up, then ask what happens on a schedule, with no person involved (a nightly job is an actor too). For the library:

Goals have a level. Cockburn's names (from memory) are cloud, kite, sea level, fish and clam. The useful one is sea level, or "user goal": something a person does in one sitting that is worth doing for its own sake, such as "Borrow a book". Above it ("Run the library") is too big to describe; below it ("Enter the card number") is a step, not a goal. A quick test: after finishing it, would the actor consider the job done, and could they walk away?

The Use Case Diagram

PlantUML, rendered here. The rectangle is the scope; actors stand outside it; each line says "this actor takes part in this use case".

That is the whole use case diagram, and it is useful for exactly one thing: showing the scope and the cast on one page, so a customer can say "you forgot that members can renew". Its limits are as important:

• It says nothing about what happens. "Borrow a book" is an ellipse; whether a member with fines can borrow, and what the librarian sees if not, is in the description below, not the picture.
• It has no order and no flow. Neither arrows nor position mean "first".
• It does not scale. Past a dozen ellipses it becomes wallpaper. Group by actor or by area into several diagrams.
• The arrowheads are a drawing convention (from memory of the UML notation, where the line between an actor and a use case is an association). Here the arrow runs from the primary actor to the use case, and from a use case to a supporting actor it needs.

Many teams keep only a list of use case names and put the effort into the descriptions. That is a fair choice.

The Use Case Description

The description is the real content. A common layout (Cockburn's, as I remember it) has these parts:

The library's "Borrow a Book", written out in full:

How It Reads

• The steps are about the actor and the system, not the screen. "The Librarian enters the card number and the ISBN" does not say whether that is a form, a scanner or a command line; deciding that is design.
• Each check is its own step (3 to 6), because each can fail differently, and each failure is an extension with the same number. This is where the value is: the main scenario is short and obvious, and the extensions list contains the decisions a developer would otherwise make silently.
• Extensions say how the use case ends, so no flow is left hanging. 4a even links to another use case (Pay a fine) and says whether to resume.
• The minimal guarantee is a promise about failure: a refused loan changes nothing. That sentence is cheap to write and expensive to forget, because a half-recorded loan is a bug nobody notices until the data is wrong.
• The open questions are part of the document. A use case written by someone who does not run the library will contain guesses; marking them is honest and tells you what to ask.

From Description to Check

A use case that cannot be turned into a test is probably vague. Here the description above became a Python function, with each numbered step and each extension as a comment in the code at the place it happens, and one test per flow. This is not the design you will end up with (who owns these checks is chapter 6's question); it is a way to make the description execute.

Two observations from doing this. First, writing the code found a missing extension. My first version of the description had no extension 2a: the code looked the ISBN up in the catalogue, and a book that was not there raised a Python KeyError, not a refusal the Librarian could read:

The description was incomplete; the code was merely the first thing to ask the awkward question. I added extension 2a, the test for it, and ran again. Second, I tested the tests. The minimal guarantee ("a refusal changes nothing") is checked by comparing a deep copy of the data before and after every refusal. To see whether that test could fail, I ran the suite against a version of borrow with a deliberate bug that changes the copy's state before the checks that may refuse:

Six tests failed, so the guarantee is really being checked. (Test code that never fails on broken code proves nothing; Build a Chatbot: From API Call to Deployed Bot 11 made the same point with simulations.) Note what the tests do not establish: that 21 days and a limit of five are right. Only the librarian can say.

Use Cases and User Stories

The Software Development Lifecycle 5 covers requirements and user stories; this section only relates the two. A story such as "As a member, I want to borrow a book so that I can read it at home" is a short reminder of a need, meant to start a conversation. A use case is what that conversation produces when the goal has real flows: the steps, the checks and the failures. They are not rivals.

A practical way to use both: let the use case supply the stories. "Borrow a book" gives one story for the main scenario and one for each extension that is worth building separately ("As a member with fines, I want to be told why I was refused and how to fix it"); the extensions double as acceptance criteria.

Include and Extend, and Why to Be Sparing

Use cases can relate to each other in two ways (from memory of the UML standard and its usual explanations). Include: the base use case always performs the included one, as a step; use it to share a piece of behaviour that several use cases need. Extend: the extending use case optionally adds behaviour to the base at a named point, under a condition; the arrow runs from the extension to the base. A small example, rendered:

Borrowing and renewing both include "Check eligibility". "Pay a fine" can extend "Return a book" when the return is late.

Read the arrows: an include arrow points to the included use case; an extend arrow points to the base. People draw them backwards constantly. And a warning: the temptation is to overuse both. Splitting use cases into include-pieces turns the description into a functional decomposition (a flowchart in disguise), and the readers lose the story. Reach for them only when the sharing is real (the same several steps in several use cases) or the optional behaviour genuinely belongs elsewhere. Writing the extension inline ("4a. The Member has unpaid fines...") is usually clearer. In the Borrow description above I did exactly that, and referred to Pay a fine by name instead of drawing an extend relationship.

Common Mistakes

Hands-On Exercises