ICONIX Process in Theory (aka Disambiguation and Prefactoring)

ICONIX Process is about driving a software design from behavior requirements, one step at a time. In other words, it’s about writing the user manual first (or at least a couple of paragraphs of it at a time, in the form of use cases); double checking the use cases to ensure that we’ve accounted for both sunny-day and rainy-day scenarios, and that the behavior description we’ve written down is really the behavior that the users want; making sure we’ve defined a set of objects (classes, really) that can collaborate to implement the required behavior; and then checking that we have the right set of attributes and operations on those classes.

When working through the various steps of ICONIX Process, what we’re really doing is distilling the behavior requirements to a more complete, more precise, and less ambiguous form. In other words, we’re disambiguating the behavior requirements and then driving the software design from these disambiguated requirements. So we make sure that we’re building the right system (i.e., we understand the required behavior) and then that we’re building the system right (i.e., we define a well-factored set of classes with appropriate attributes and methods that will implement the required behavior). In short, disambiguation of requirements is about building the right system, and prefactoring of the design is about building the system right.

In ICONIX Process, everything has a primary purpose:

• Use case text: Define the behavior requirements.

• Domain model: Describe the real-world objects and relationships.

• Robustness diagram: Disambiguate the behavior requirements (and tie them to the object model).

• Sequence diagram: Allocate behavior (i.e., assign functions to classes).

So you repeat the following for every scenario you’re going to build:

1. Define the behavior requirements.

2. Disambiguate the behavior requirements and tie them to the object model.

3. Assign functions to classes.

This is the essence of use case–driven development.

Three key principles underlie the approach, which, as you can see, is inside out, outside in, and top down, all at the same time:

• Work inward from the requirements.

• Work outward from the domain objects.

• Drill down from high-level models to detailed design.

What Is a Use Case?

A use case is a sequence of actions that an actor (usually a person, but perhaps an external entity, such as another system) performs within a system to achieve a particular goal.

A use case is most effectively stated from the perspective of the user as a present-tense verb phrase in active voice. For example, one use case within a travel website might be called “Find Hotel,” while a portfolio system is likely to contain use cases named “Do Trade Entry,” “Update Portfolio Information,” and “Generate Reports.”

A complete and unambiguous use case describes one aspect of the system without presuming any specific design or implementation. The result of use case modeling should be that all required system functionality is described in the use cases. If you don’t adhere to this basic principle, you run the risk of having your bright engineers build a cool system that isn’t what your customers want.

Tip 

Don’t waste time with long and involved use case templates. Templates that include sections for preconditions, postconditions, and so forth tend to be a real energy drain and don’t give much in return. A use case should be a short, succinct statement of a user’s interaction with the system to achieve a specific goal—nothing more.

THE TWO-PARAGRAPH RULE

A useful rule of thumb when writing use cases is to limit them to a maximum of two paragraphs. If the use case text goes beyond this, it probably wants to be more than one use case.

This two-paragraph rule (or guideline) is intended to make it easier to create a sequence diagram for every use case in the model. We intend to bring each of our use case scenarios to code, and we aim to prefactor our design and make sure we’ve done a good, clean allocation of behavior (assigning operations to classes) using sequence diagrams. Two paragraphs is not an absolute, but two sentences is too small to bother with, and two pages is too long. The happy medium lies somewhere around two paragraphs.

If you’ve ever tried to read a sequence diagram for a three-page use case, the reason for the two-paragraph rule is obvious. You won’t be able to print the sequence diagram on an 8×10 sheet of paper in any font that a human can read. Therefore, your diagram won’t be able to be reviewed, either by yourself or by your peers. It will also contain more errors than a diagram that is comprehensible and reviewable.

MODELING QUESTION: IS A USE CASE A REQUIREMENT?

The relationship between requirements and use cases is the subject of much heated debate in the OO community. Here’s a handy mantra to sum up the answer:

Requirements are requirements, use cases are use cases; requirements are not use cases, use cases are not requirements.

However (it just wasn’t going to be that easy, was it?), use cases are really behavior requirements. Here’s a slightly more elaborate way of distinguishing use cases from requirements:

• A use case describes a unit of behavior.

• A requirement describes a law that governs behavior.

• A use case can satisfy one or more functional requirements.

• A functional requirement may be satisfied by one or more use cases.

Note our use of the words “may” and “functional.” A system will have its share of functional requirements, but it will also have other types of requirements, such as those involving performance and maintainability, that won’t map well to use cases.

One of the really common use case modeling errors is to try to do everything in use cases. However, by remembering to keep nonfunctional requirements out of the use cases, the whole thing becomes a lot easier: just keep a separate list of requirements (which may include some behavior requirements at a high level), and fill in the functional details via use cases.

What Is an Actor?

An actor represents a role a user can play with regard to a system or an entity, such as another system or a database, that will reside outside the system being modeled. The total set of actors within a use case model reflects everything that needs to exchange information with the system. Within a hotel booking system (see the example project in Part 2), actors may include Travel Agent Staff, Administrative Staff, and end users (people going on the web to book hotels). A portfolio system would have actors called Risk Manager and Trader.

A user can serve as more than one type of actor. For instance, a Travel Agent might also perform administrative duties. Similarly, more than one user can appear as a particular actor (e.g., multiple Trading Assistants interacting with a portfolio system).

We show use cases and actors on a use case diagram. Within a use case diagram, use cases appear as ovals, generally in the middle of the diagram, and actors appear as stick figures, usually to the left and right of the ovals. (These layout conventions are optional, of course. If you like your actors on the top and the ovals on the bottom, feel free.)

Figure 3-2 shows a use case diagram from the example project we cover in Part 2 of this book.

Figure 3-2: Example use case diagram

As we’ll explore in Chapter 9), an actor can also be used to represent a specific target user or persona when exploring the user goals that the system needs to implement. Applying the use cases to specific personas instead of generic actors can help to make the product more focused on the user’s goals.