We're back with another three articles containing material excerpted from our recently published workbook, Applied Use Case-Driven Object Modeling (Addison-Wesley, 2001). We're following the process detailed in our first book, Use Case-Driven Object Modeling with UML (Addison-Wesley, 1999), as we dissect the design of an Internet bookstore.
An essential part of the modeling process is requirements review, which aims to ensure that the use cases and the domain model work together to address customers' functional requirements. Clarifying customers' concepts of their own needs to expedite and improve the design process is another important component.
Many believe that customers never know what they want; the requirements change weekly, sometimes daily or even hourly, thereby rationalizing the avoidance of analysis and design. This is an enormous cop-out. It's the analyst's job to help customers understand and refine their requirements. With use cases, prototypes and domain models, we make this process work.
Figure 1. The Modeling Process An essential part of the modeling process is requirements review, which aims to ensure that the use cases and the domain model work together to address the customers' functional requirements. |
Figure 1 shows the location of a requirements review in the overall ICONIX process.
The Key Elements
Requirements review must involve representatives of both the customer(s) and the development team, as well as any necessary managers. The goal is to ensure that the system use cases, together with the domain model and whatever prototype elements are in place, capture the customers' functional requirements. This process works best when everyone is in a room together with a facilitator or moderator who keeps the dialogue on track and a scribe who records the results and plans.
Traceability is key: We need to elucidate how each requirement traces into one or more use cases, and how one or more classes from the domain model and one or more elements of the prototype work together with those use cases to address the requirement.
A fundamental question that every development effort must answer is: What are the real-world objects we need to model, and how do they relate to each other? In the ICONIX process, domain modeling forms the foundation of the static segment of our UML model. When we build a domain model, we first identify abstractions in the real world—that is, the main conceptual objects that will participate in this system.
When we design object-oriented software, we try to model it on these real-world, problem-space objects because the real world changes less frequently than do software requirements. The domain model's initial class diagrams must be developed to the point where you can use them to begin writing code, so you need to capture key abstractions early in the process.
Another fundamental question is: What are the system users trying to do? During use case modeling, and, by extension, requirements review, we must nail down our users' behavior in great detail; software behavior is dictated by user requirements.
It's a good idea to employ prototypes to help define the use cases, and we encourage our clients to use rapid prototyping as frequently as possible. Sitting developers and users down together to build something that will demonstrate "proof of concept" can be helpful. However—and this is the big "however" that separates us from the Extreme Programming community—don't mistake your proof-of-concept prototype for deliverable software—even if you've run some unit tests hundreds of times—unless you're fond of your users pressing Ctrl-Alt-Delete when confronted with the "blue screen of death."
Proof-of-concept prototypes are built to effect rapid delivery at the expense of robust, "bullet-proof" design. To demonstrate proof of concept, you're trying to build something that looks cosmetically close to what your users want, as fast as you possibly can. So, you're likely to "do the simplest thing that can possibly work," to borrow a catchy slogan. It's a lot like bringing in a construction crew to put up a movie set: They can build a "house" (actually a facade) that looks fantastic, in just a fraction of the time it takes to build a real house—but it will lack a few minor details, like blueprints, electrical schematics and plumbing plans. Imagine trying to refactor this movie facade into a real house.
Always keep in mind that proof-of-concept prototypes are just like facade houses. What do you do if you have pointy-haired management that can't tell the difference? It's simple: Don't build your prototypes in code—just work with pencil-and-paper line drawings.
Taking this idea one step farther, we've found that exploring the graphical user interface (GUI) design along with the required system behavior provides great benefits. This involves iterating, with the users, the presentation aspects of the system, and, after achieving closure on a few screens, writing the associated use cases. This back-and-forth approach can be very effective in the right environment. Extending this concept to your requirements review, text for a given use case should match the associated GUI element(s), in terms of the use case's descriptions of the basic nature of those elements and the system's responses to actions that the actor performs.
Some prominent people in the OO community advocate the opposite, insisting that use case text shouldn't describe GUI specifics. They also urge you to avoid discussing anything specific and recommend that your text be as abstract (or teleocentric, which means goal-oriented) as possible.
We remain unconvinced. You can't drive an abstract use case down through code nearly as effectively as you can drive a specific use case. You shouldn't discuss whether this field contains a set of radio buttons or that window has both vertical and horizontal scroll bars, but you should talk about the "call and response" of actor and system, and you should name the objects that come into play, as well. This is the best way to incorporate a high level of traceability from your use cases into your analysis and design.
Requirements review is also the place for a use case grammar check. A use case is most effectively stated from the perspective of the user as a set of present-tense verb phrases in active voice. Engineers' penchant for passive voice is well established, but as we just said, use cases should state the actions that the user performs and the system's responses to those actions. This kind of text is effective only in active voice.
Another critical aspect of use case modeling involves alternate courses of action. It's crucial to think of all possible alternate courses of action for each use case whenever possible, which should be most of the time. Basic courses of action are generally easier to identify and write text for. This doesn't mean, however, that you should put off dealing with alternative courses until, say, the detailed design phase—far from it. In fact, all too often, we've seen omissions cause serious problems at that point; taking the time to write out alternative courses up front would have saved the team considerable grief.
When important alternative courses of action aren't uncovered until the coding and debugging stages, 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. You must be relentless. Ask, "What else can happen? Are there any other things that can happen? Are you sure?" Keep asking those questions until you have a rich set of alternative courses. Trust us: Grief at this point is much easier to take than grief during, say, integration testing.
Also, stay away from long, complicated use case templates. Spaces for preconditions and postconditions are generally present on these templates, along with many other things that are redundant at best, and annoying at worst. We like to think of this as the "long form" approach to use case modeling, compared 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.
The Top 10 Errors
The flip side of the principles just discussed are a number of common errors that our students make when they're doing requirements review for their projects. Our "Top 10" list of errors follows.
10. Not reviewing requirements at all. Instead, invite "feature-itis" by letting the coders build what they want. One of the fundamental tenets of Extreme Programming (XP) is that since requirements change every day, it doesn't make much sense to try to deal with them explicitly. Proponents of this approach lose not only requirements traceability, but the trust between customers and developers that can come solely from intensive, face-to-face negotiation.
The XP folks even have hip slogans to describe this phenomenon. Kent Beck used one to diagnose the failure of the C3 project on their Wiki Web site: " … the fundamental problem was [that] the Gold Owner and Goal Donor weren't the same. The customer feeding stories to the team didn't care about the same things as the managers evaluating the team's performance … The new customers wanted tweaks to the existing system more than they wanted to turn off the next mainframe payroll system. IT management wanted to turn off the next mainframe payroll system." Translation: In XP lingo, the Goal Donor is the customer representative who sits in the room with the coders, who explain that it's OK to change requirements midstream, while the Gold Owner is the project sponsor. In the case of C3 (a Y2K mainframe payroll replacement project), the Gold Owner "inexplicably" pulled the plug in February 2000, when, after four years of labor, it became apparent that the program (no doubt chock-full of cool features) was paying only one-third of the employees.
Would requirements review have saved C3? We can't say for certain, but we do know that "feature-itis," which comes at the expense of scheduling, is a predictable result of letting the programming team decide (and continuously change) the requirements priorities without informing the project sponsors.
9. Not ensuring that the use case text matches the desired system behavior. The phrase "use case-driven" refers to the principle of employing use cases—which capture the "what" that the system needs to do—to drive the system's "how:"analysis, design, testing and implementation. If your use case text doesn't correlate with what your users want the system to do, you're going to build the wrong system.
8. Not using any kind of GUI prototype or screen mock-up to help validate system behavior. Prototypes, whether they take the form of fully workable front ends, drawings on scraps of paper or something in between, generally jump-start the task of discovering and exploring use cases. If your use case text matches the prototype's navigation, you're likely to build the right system. Without this visual frame of reference, you run the risk of building stuff that doesn't match your users' requirements as expressed in the use cases.
7. Keeping your use cases at such a high level of abstraction that your nontechnical clients have no clue what they're about. Good use cases have enough details to drive the system's development from requirements discovery all the way through code. They also serve as an effective tool for negotiating requirements with customers and managing their expectations. However, this works only if the use case text is specific: The actor does this; the system does this. A customer can't sign off on a use case that he or she doesn't understand.
6. The domain model doesn't accurately reflect the real-world conceptual objects. You'll build code from class diagrams that have ample detail. These diagrams evolve from high-level class diagrams that show the initial domain model as you explore the dynamic behavior of the system you're designing. This evolution simply won't happen the way it should if you don't put the right objects in place at the beginning.
5. The use case text doesn't reference the domain objects. We discussed domain modeling before we talked about use case modeling in Applied Use Case-Driven Object Modeling because domain modeling enables you to build a glossary of use case text terminology (see also "Driving Design: The Problem Domain" and "Top 10 Use Case Mistakes," Jan. and Feb. 2001). This technique will help you to be specific in your use cases, and it'll also advance that goal of traceability we keep mentioning, because your use cases and your class diagrams will work together. In addition, robustness analysis will be much faster if you've already named your objects in your use case text.
4. Not questioning use cases that have no alternate courses of action. It's been our experience that more than 90 percent of good use cases have at least one alternate course of action. Words like "check," "ensure," "validate" and "verify" indicate that there's at least one alternate course, associated with an error condition. A use case is also likely to have at least one path that the actor takes more frequently than the one specified by the basic course. Be diligent about digging for these other paths.
3. Not questioning whether all alternate courses of action have been considered on every use case. To find alternate courses, question every sentence in your basic course. What could possibly go wrong? Can the actor take another path? Could the system respond in different ways? Be relentless in your search for alternate courses; much of the interesting behavior of your system will be reflected in them, not in the basic courses.
2. Not worrying if your use cases are written in passive voice. Your use cases should describe actions that the actors and system perform. Obviously, actions are best expressed with action verbs, and active voice is their appropriate voice. Passive voice is appropriate only when the writer doesn't know who or what is performing a given action—and that should never occur with use case text.
1. Not worrying if your use cases are four pages long. The basic course of a use case should be two or three paragraphs long at most. Each alternate course should be a sentence or two. Sometimes you'll have shorter use cases, especially when they serve as connecting tissue, and occasionally you'll need longer use cases. But you should employ techniques like the invokes and precedes constructs discussed in Use Case-Driven Object Modeling with UML to factor out common behavior, so you can write concise use cases that you're more likely to be able to reuse.
Next month, we'll discuss preliminary design review (PDR), a process that ensures that robustness diagrams exist and are consistent for all use cases. PDR also certifies that the domain model has a rich set of attributes that correspond with the prototypes that are in place, makes sure that the domain model contains all the objects needed by the use cases, and determines if the development team is ready to move to detailed design. See you then.