This chapter addresses a fundamental question that every development effort must ask: What are the users of the system trying to do? We’re going to focus our efforts on trying to capture our users’ actions, and the associated system responses, in great detail because the software behavior is dictated by the user requirements. In other words, what we need the software to do depends on how the users are accessing it and what the users are trying to do. This often relates to screens and user interfaces.
Figure 3-1 shows where use case modeling resides within the “big picture” for the ICONIX process. As you can see, we think it’s a good idea to use prototypes to help define the use cases. And, we do our use case model, along with our domain model, right at the very beginning of our project. The entire dynamic part of the object model is directly driven from the use case model we put together. Since the dynamic model drives the static model, the use cases are also driving our static model, as well.
Figure 3-1 also shows that we’re continuously updating and refining our static model based on further analysis of these use cases as we do our robustness and sequence diagrams. We’re constantly updating our static model as we walk through the scenarios. That’s how it evolves from the first-cut domain model to our detailed design-level static model. We’re completely use case driven in this approach, in that our software architecture and our software design are both driven from our analysis of usage scenarios.
The whole dynamic model is very much an outside-in type of approach. We start with users who are outside our system, and we work our way in to expose all details of the software behavior. From that, the software structure that supports that behavior is created. But we’re working inward from the outside of the system, one scenario at a time. Because the use cases are the fundamental unit of decomposition in this modeling effort, everything else is directly driven from this outside-in approach. As a result, we’re reliably able to design systems that meet our user requirements, which is no small accomplishment.
The task of building use cases for your new system is based on identifying as many as you can up front and then establishing a continuous loop of writing and refining the text that describes them. Along the way, you will discover new use cases and also factor out commonality in usage.
You should keep one overriding principle in mind at all times in your effort to identify use cases: They should have strong correlations with material in the user manual for the system. It should be obvious what the connection is between each use case and a distinct section of your user guide. This reinforces the fundamental notion that you are conforming the design of your system to the viewpoints of the users. It also provides a convenient summary of what “use case driven” means: Write the user manual, then write the code. If you’re reengineering a legacy system, you can simply work from the user manual backward, making any necessary changes as you go.
Once you have some text in place for a use case, it’s time to refine it by making sure the sentences are clear and discrete, the basic format of your text is noun-verb-noun, and the actors and potential domain objects are easily identifiable. You should also update your domain model (see Chapter 2) as you discover new objects and expand your understanding of the objects you’d previously found. And, it’s very important to think of all possible alternate courses of action for each use case wherever possible, which should be a large majority of the time. Note that robustness analysis (see Chapter 5) will be very helpful toward accomplishing all of this refinement.
Although some authors encourage the use of voluminous use case templates, here’s what we recommend to every one of our clients:
Create a use case template that has areas labeled Basic Course and Alternative Courses. Don’t put anything else in there; it’ll just distract you.
Ask “What happens?” This will get the basic course of action started.
Ask “And then what happens?” Keep asking that question until you have all the details of your basic course on paper.
Ask, “What else can happen?” Be relentless. Are there any other things that can happen? Are you sure? Keep asking those questions until you have a rich set of alternative courses written down. Trust us: Grief at this point is much easier to take than grief during, say, integration testing.
The goal is not to construct an elegant use case model; the goal is to account for everything the user might do.
You’ll review this material during a requirements review (see Chapter 4); you’ll review it again during a preliminary design review (see Chapter 6); and you’ll review it once more during a critical design review (see Chapter 8). This may seem excessive, but keep in mind that the more well-defined the system behavior, the easier it’s going to be to build the system.
You can use several mechanisms to factor out common usage, such as error handling, from sets of use cases. This is usually a good thing to do because breaking usage down to atomic levels will make your analysis effort easier and save you a lot of time when you’re drawing sequence diagrams. Whether you use the UML’s use case generalization and include and extend relationships, or the invoke and precede relationships from the Open Modeling Language (OML), which we recommend in Use Case Driven Object Modeling with UML, your goal should be a set of small, precise, reusable use cases.
We recommend grouping use cases into packages, primarily because these packages form logical boundaries for dividing work among subteams. A good rule to follow is: Each package should correspond with a chapter, or at least a major section, in your user manual.
You should feel comfortable proceeding to the next phases of the development process when you’ve achieved the following goals of use case modeling:
You’ve built use cases that together account for all of the desired functionality of the system.
You’ve produced clear and concise written descriptions of the basic course of action, along with appropriate alternative courses of action, for each use case.
You’ve factored out scenarios common to more than one use case, using whichever constructs you’re most comfortable using.
The flip side of the principles we just discussed takes the form of a number of common errors that we have seen students make when they’re doing use case modeling on their projects for the first time. Our “Top 10” list follows.
Requirements are generally stated in terms of what the system shall do. Usage scenarios describe actions that the users are taking and the responses that the system generates. Eventually, we’re going to use our use case text as a runtime behavioral spec for the scenario we’re describing, and this text will sit on the left margin of a sequence diagram. We want to be able to easily see how the system (shown with objects and messages) is implementing the desired behavior, as described in the use case text. So, we need to keep a clear distinction between (active voice) usage descriptions (behavior) and (passive voice) system requirements.
Not only shouldn’t your use case text include too many presentation details, but it should be relatively free of details about the fields on your screens, as well. Field names often match up directly with the names of attributes on your domain classes, which we talked about in Chapter 2. If you find yourself starting to list the names of, say, 13 fields from the screen in your use case text, stop. Open the domain model, find the class(es) where those attributes belong, and capture them where they’ll do you some good—as attributes. Later, when you need them, they’ll be there. Methods shouldn’t be named or described in case text because they represent how the system will do things, as opposed to what the system will do.
When it comes to writing text for use cases, expansive is preferable to terse. You’re going to need to address all of the details of user actions and system responses as you move into robustness analysis and interaction modeling, so you might as well put some of those details in your use cases up front. Remember also that your use cases will serve as the foundation for your user manual, and it’s always better to err on the side of too much detail rather than not enough when it comes to user documentation.
One of the fundamental notions of “use case driven” is that the development team conforms the design of the system to the viewpoints of the users. You can’t do this without being specific as to what actions the users will be performing on your screens. As we mentioned for item 9, you don’t need to talk about fields in your use case text, and you also don’t want to go into any detail about the cosmetic appearance of your screens; you can let your prototypes, in whatever form they take, do that work for you. You do, however, need to discuss those features of the user interface that allow the user to tell the system to do something.
Boundary objects. are the objects with which actors will be interacting. These frequently include windows, screens, dialogs, and menus. In keeping with our themes of including ample detail and being explicit about user navigation, we submit that it’s necessary to name your boundary objects explicitly in your use case text. Another reason that it’s important to do this is that you’re going to explore the behavior of these objects during robustness analysis (see Chapter 5), and it can only help reduce ambiguity and confusion to name them early.
A use case is most effectively stated from the perspective of the user as a set of present-tense verb phrases in active voice. The tendency of engineers to use passive voice is well-established, but use cases should state the actions that the user performs, and the system’s responses to those actions, and this kind of text is only effective when it’s stated in active voice.
The narrative of a use case should be event-response oriented, as in, “The system does this when the user does that.” The use case should capture a good deal of what happens “under the covers” in response to what the actor is doing, such as creating new objects, validating user input, or generating error messages. Remember that your use case text describes both sides of the dialog between the user and the system, and that all of the software behavior that you’re trying to discover happens on the system side of that dialog. If you leave out the system responses, you ignore the software behavior.
Basic courses of action are generally easier to identify and write text for. That doesn’t mean, however, that you should put off dealing with alternative courses until, say, detailed design. In fact, it’s been our experience that when important alternative courses of action are not uncovered until coding and debugging, the programmer responsible for writing or fixing the code tends to treat them in ways that are most convenient for him or her. Needless to say, this isn’t healthy for a project.
Several prominent authors advocate the use of long, complicated use case templates. Spaces for preconditions and postconditions are generally present on these templates. We like to think of this as the 1040 “long form” approach to use case modeling, in comparison to the 1040EZ-like template that we advocate (two headings: Basic Course and Alternate Course). You shouldn’t insist on using long and complex use case templates just because they appeared in a book or article. Don’t waste your time.
In our years of teaching use case driven development, we have yet to come across a situation in which we’ve needed more than one mechanism for factoring out commonality. Whether you use the UML’s include construct, or the OML’s invoke and precede mechanisms, or something else that you’re comfortable with, doesn’t matter; what matters is that you pick one way of doing things and stick with it. Having two similar constructs is worse than having only one. It’s too easy to get confused—and bogged down—when you try to use both. Don’t spin your wheels.
The following exercises, taken from the use case model for our Internet Bookstore, are designed to test your ability to spot the top 10 mistakes that people make during use case modeling. (The full use case model is presented in Appendix.) Each page with a red label at the top contains three or four of these mistakes; your task is to write corrections on the page near the erroneous material. Following each of these pages is a page with a white label inside a black box at the top; this page contains corrected material (in italics) and explanations of the top 10 rules that were violated on the previous page. Happy hunting!
[from Open Account]
Basic Course: The Customer enters the required information. The system validates the information and creates a new Account object.
Alternate Course: If any data is invalid, the system displays an appropriate error message.
[from Search by Author]
The user submits the request. The system displays another page that contains the search results.
[from Log In]
The Customer enters his or her user ID and password, and then clicks the Log In button. The system returns the Customer to the Home Page.
Basic Course: The Customer types his or her name, an email address, and a password (twice), and then presses the Create Account button. The system ensures that the Customer has provided valid data, and then creates an Account object using that data. Then the system returns the Customer to the Home Page.
Alternate Courses:
If the Customer did not provide a name, the system displays an error message to that effect and prompts the Customer to type a name.
If the Customer provided an email address that’s not in the correct form, the system displays an error message to that effect and prompts the Customer to type a different address.
If the Customer provided a password that is too short, the system displays an error message to that effect and prompts the Customer to type a longer password.
If the Customer did not type the same password twice, the system displays an error message to that effect and prompts the Customer to type the password correctly the second time.
The Customer types the name of an Author on the Search Page, and then presses the Search button. The system…retrieves all of the Books with which that Author is associated….Then the system displays the list of Books on the Search Results Page.
Basic Course: The Customer enters his or her user ID and password, and then clicks the Log In button. The system validates the login information against the persistent Account data, and then returns the Customer to the Home Page.
Alternate Course: If the system cannot find the specified userID,
On the previous page:
The first use case is too terse. There’s no reference to what kind of information the Customer is entering, nor to the page he or she is looking at. The text doesn’t explain what’s involved in the validation of the data the Customer entered. And the use case doesn’t describe how the Customer needs to respond to an error condition.
The second use case fragment doesn’t contain explicit names for the relevant boundary objects.
The third use case fragment is lacking alternate courses, even though it should be fairly obvious from the context that some validation needs to occur and that there are several possible error conditions.
[from Log In]
Name: Log In
Goal: To log a customer into the system.
Precondition: The Customer is not already logged into the system.
Basic Course: The Customer enters his or her user ID and password, and then clicks the Log In button….
Alternate Courses: …
Postcondition: The Customer is logged into the system.
[from Edit Contents of Shopping Cart]
On the Shopping Cart Page, the Customer modifies the quantity of an Item in the Shopping Cart, and then presses the Update button. Then the Customer presses the Continue Shopping button.
[from Cancel Order]
Basic Course: The system displays the relevant information for the Order on the Cancel Order Page, including its contents and the shipping address. The Customer presses the Confirm Cancel button…
Basic Course: The Customer enters his or her user ID and password, and then clicks the Log In button….
On the Shopping Cart Page, the Customer modifies the quantity of an Item in the Shopping Cart, and then presses the Update button. The system stores the new quantity, and then computes and displays the new cost for that Item….
Basic Course: The system ensures that the Order is cancellable (in other words, that its status isn’t “shipping” or “shipped”). Then the system displays the relevant information for the Order on the Cancel Order Page, including its contents and the shipping address. The Customer presses the Confirm Cancel button. The system marks the Order status as “deleted,” and then invokes the Return Items to Inventory use case.
Alternate Course: If the status of the Order is “shipping” or “shipped,” the system displays a message indicating that it’s too late for the Customer to cancel the order.
On the previous page:
The first use case fragment shows how useless it can be to be obsessive about using a complicated use case template. The name of the use case expresses the goal clearly enough; the content of the basic course will make the stated precondition and postcondition quite redundant.
The second use case fragment doesn’t specify what the system does in response to the Customer pressing the Update button, including possibly deleting an Item.
The third use case fragment doesn’t allow for the possibility that the Order might have a status that prevents it from being cancelled.
[from Search by Author]
The Customer types the name of an Author, and then submits a search request….The system retrieves the important details about each Book, and then displays the list of Books.
[from Edit Contents of Shopping Cart]
Basic Course: If the Customer modifies the quantity of an Item in the Shopping Cart, and then presses the Update button, the system will store the new quantity, and then compute and display the new cost for that Item….
Alternate Course: The system will delete an Item from the Shopping Cart if the quantity of that Item in that Shopping Cart becomes 0.
[from Process Received Shipment]
The Receiving Clerk ensures that the Line Items listed on the Purchase Order match the physical items. The Clerk waves the bar code on the packing slip under the sensor at the receiving station. The system executes a “change order status” method to change the Order status to “fulfilled,”and then calls the changeQuantityOnHand method for each of the variousBooks. The Clerk hands the Books off to the Inventory Clerk.
The Customer types the name of an Author on the Search Page, and then presses the Search button….The system retrieves the important details about each Book….Then the system displays the list of Books on the Search Results Page….
Basic Course: On the Shopping Cart Page, the Customer modifies the quantity of an Item in the Shopping Cart, and then presses the Update button. The system stores the new quantity, and then computes and displays the new cost for that Item….
Alternate Course: If the Customer changes the quantity of the Item to 0, the system deletes that Item from the Shopping Cart.
The Receiving Clerk ensures that the Line Items listed on the Purchase Order match the physical items. The Clerk waves the bar code on the packing slip under the sensor at the receiving station. The system changes the status of the Purchase Order to “fulfilled” and updates the quantity on hand values for the various Books. The Clerk hands the Books off to the Inventory Clerk.
On the previous page:
The first use case fragment doesn’t name the boundary object.
The second use case fragment reads more like part of a requirements spec than a use case.
The third use case fragment refers to two methods.
[from Check Out]
The Customer selects a billing method and presses the Use This Billing Information button. Then the Customer presses the Confirm Order button. The use case ends.
[from Ship Order]
The Clerk waves the bar code on the packing slip under the sensor at the shipping station. The system changes the status of the Order to “shipping.” Then the system retrieves the Shipping Method that the Customer specified for this Order, and displays it on the Shipping Station Console….
[from Track Recent Orders]
The Customer clicks on a link. The system retrieves and displays the Contents of the Order, in view-only mode, on the Order Details Page. This display shows the relevant values of the Order object at the top of the page and the Item details, including the basics about each Book that the Customer ordered (but not the thumbnails), below that. The Customer presses OK to return to the Order Tracking Page.
The Customer selects a billing method and presses the Use This Billing Information button. The system associates the given Billing Info object with the Candidate Order. Then the system displays the Confirm Order Page.
The Customer presses the Confirm Order button. The system converts the Candidate Order to an Order and destroys the Shopping Cart. Then the system returns control to the use case from which this use case received control.
Basic Course: The Shipping Clerk ensures that the Items listed on the packing slip for the Order match the physical items. The Clerk waves the bar code on the packing slip under the sensor at the shipping station. The system changes the status of the Order to “shipping.” Then the system retrieves the Shipping Method that the Customer specified for this Order, and displays it on the Shipping Station Console….
Alternate Course: If the Shipping Clerk finds a mismatch between the Order and the physical items, the Clerk stops processing of the Order until he or she is able to make a match.
The Customer clicks on a link. The system retrieves and displays the contents of the Order, in view-only mode, on the Order Details Page. [note missing text] The Customer presses OK to return to the Order Tracking Page.
On the previous page:
The first use case fragment doesn’t describe what happens when the Customer presses the Use This Billing Information button or when he or she presses Confirm Order.
The second use case fragment doesn’t allow for the possibility that the set of Items that the Shipping Clerk has in front of him or her doesn’t match what’s on the packing slip.
The third use case contains too many details about what the Order Details page will look like.
[from Ship Order]
The Clerk finishes packaging the Order, and records the tracking number, and then sends the package out via the associated Shipper.
[from Track Recent Orders]
The system retrieves and displays the Orders that the Customer has Placed within the last 30 days….The Customer requests details for an Order. The system retrieves and displays the contents of the Order, in view-only mode. The Customer returns to the list of Orders when he or she is finished looking at the details of the given Order.
[from Browse List of Books]
The Customer clicks on a Category on the Browse Books Page. The System invokes the “displayYourSubcategories” method on the Category object. This process continues until there are no more subcategories, at which point the system displays the Books in the lowest subcategory.
The Clerk weighs the set of physical items. The Clerk packages the Items. The Clerk attaches a manifest appropriate for the given shipping method. The Clerk waves the bar code on the manifest under the sensor. The system records the tracking number from the bar code for the given Order. The Clerk sends the package out via the associated Shipper.
The system retrieves the Orders that the Customer has placed within the last 30 days, and displays these Orders on the Order Tracking Page. Each entry has the Order ID (in the form of a link),…The Customer clicks on a link. The system retrieves and displays the contents of the Order, in view-only mode, on the Order Details Page. The Customer presses OK to return to the Order Tracking Page.
The Customer clicks on a Category on the Browse Books Page. The system displays the subcategories within that Category. This process continues until there are no more subcategories, at which point the system displays the Books in the lowest subcategory.
On the previous page:
The first use case fragment doesn’t specify how the Shipping Clerk records the tracking number and thus how it gets associated with the given Order.
The second use case fragment omits several details about where the list of Orders and the Order details appear and how the Customer navigates between these.
The third use case fragment describes what happens in terms of a method rather than from the actor’s standpoint.
Figure 3-2 shows the full use case diagram for our Internet Bookstore. This diagram shows the use cases that provide the fragments presented within the exercises, along with the actors involved in those use cases.
