More About Disambiguation

Here again (because it’s worth repeating over and over) is the primary mission statement of ICONIX Process:

Root out ambiguity from the requirements, and then do a clean design.

We refer to this “rooting out ambiguity” as disambiguation, partly because that’s what it is, but also because we like the word itself (but we’d never knowingly admit to that!).

In this section, we’ll look at how ICONIX Process helps to disambiguate the requirements (which in turn greatly increases your chances of creating a clean design).

Do the Domain Model First to Avoid Ambiguity in the Use Cases

The domain model is done before use cases are written to provide a first level of disambiguation (i.e., removing namespace ambiguity from the use cases by making the team use the major nouns consistently in the use cases when they’re first drafted).

Modeling Question 

How much time should be spent on domain modeling? Generally a couple of hours. This activity should really be given an upper limit of half a day. You’re trying to pick the low-hanging fruit, and see if you can get maybe 80% or so of the most important objects from the problem domain and give them distinct and unambiguous names. Those few hours are generally some of the most productive modeling hours you’ll ever spend, because that way you don’t have some users going off and writing a number of use cases that use “shopping cart,” others that use “shopping basket,” and (if you have some British developers on your team) some that use “trolley.”

Modeling Question 

A couple of hours for domain modeling? But what if you’re writing a safety-critical system? That’s the funny thing. Even if you’re writing a safety-critical system, you really don’t need to spend more than a couple of hours (or a morning at most) on the initial domain modeling (really!). The reason is that the process assumes that the domain model is incomplete and that the first-draft use cases will be ambiguous. This is where the robustness diagrams come into play. They help fill in the gaps in the domain model while disambiguating the use cases. Since the process has this built-in disambiguation and object discovery mechanism, you can spend just a few hours domain modeling nearly any kind of system, because you don’t rely on the domain model being correct (or complete, for that matter)—instead, you assume it’s not complete, and you complete it incrementally, one scenario at a time.

Once the use cases get drafted with everyone using ad-hoc vocabulary for the domain entities, then you already have a mess to unravel. It’s far more efficient to get everybody to agree to one set of terms first (before the team invests time in writing use cases that use ambiguous terminology).

The reason this is so important is that namespace ambiguity is an insidious drain on your productivity in modeling. ICONIX Process is really a “seek-and-destroy” mission to take the ambiguity out of the requirements—the basic theory being that programming is easy (or at least much easier) when you’re coding against unambiguous requirements. So, the first step in disambiguation is to do the domain model.

Here’s a typical example (we see this sort of thing all the time) of disambiguation via domain modeling. In a recent JumpStart class, Doug was dealing with procurement of hospital supplies. The terms “PR,” “Purchase Requisition,” “Requisition,” “Purchase Requirement,” and “Requirement” were all being used interchangeably in the functional requirements descriptions. In fact, further exploration revealed that “Requirement” (e.g., “We need 300 syringes”) was something that existed before a “Purchase Requisition” was created. So the team needed to have both “Requirement” and “Purchase Requisition” on the domain model, and the use cases were written with consistent usage of the vocabulary.

Using Robustness Analysis to Disambiguate the Use Cases

After the domain model is used to disambiguate the requirements and conversations with business users (before writing the use cases), you’ll use robustness analysis to further disambiguate the use cases (after they’re written, of course). How’s that for a double safety net!

The robustness diagrams perform a more in-depth disambiguation than the domain model, because they enforce the linkage between the use cases and the object model. They also help with object discovery (i.e., discovering objects that were left off the initial domain model).

Robustness diagrams span the space that includes detailed requirements analysis and exploratory, conceptual design, thus bridging the gap between analysis and design (which we discuss in the next section). However, it’s important to not use robustness diagrams for detailed design. It’s better to leave the detailed design until the sequence diagrams (and possibly also the unit tests if you’re combining ICONIX Process with TDD; see Chapter 12).

Robustness diagrams are quick to draw (if you have a well-formed use case), and you can discard them when you’re finished with them. They’re a transitory artifact—a means of getting from one state to another.

Bridging the Gap Between Analysis and Design

As mentioned earlier, robustness analysis provides a highly useful technique to bridge the gap between analysis (the what) and design (the how). The Three Amigos (Booch, Rumbaugh, and Jacobson) point out the rather large gap between analysis and design in The Unified Modeling Language User Guide (our emphasis added):

In software, the Achilles heel of structured analysis techniques is the fact that there is a basic disconnect between its analysis model and the system’s design model. Failing to bridge this chasm causes the system as conceived and the system as built to diverge over time.In object-oriented systems, it is possible to connect all the nearly independent views of a system into one semantic whole.^[8.]

Robustness analysis plays several essential roles within ICONIX Process:

• Sanity check: Robustness analysis helps you make sure that your use case text is correct and that you haven’t specified system behavior that’s unreasonable—or impossible—given the set of objects you have to work with.

• Completeness check: Robustness analysis helps you make sure those use cases address all the necessary alternative courses of action.

• Ongoing discovery of objects: You may have missed some objects during domain modeling.

• Preliminary design: Robustness analysis helps bridge the gap between analysis and design.

Is Robustness Diagramming an Art or a Science?

Creating robustness diagrams is half art and half science. Once you see the final robustness diagram you’ll say, “Hey, how come I didn’t think of that? This is pretty easy.” Robustness diagramming can be likened to riding a bicycle: once you figure it out, it’s really easy, but it can be a bit confounding until you get the hang of it.

Programmers in particular can find it tricky to learn because they tend to think literally, whereas the robustness diagram operates at the conceptual design abstraction level. Refactoring is the result of code that has been written to the wrong conceptual design (we give a concrete example of this in Chapter 7). Constant Refactoring After Programming is the result of consistently skipping the conceptual design step and jumping directly from behavior requirements (“stories” or use case text) to detailed design.

As Figure 3-8 shows, when programmers become more skilled at manipulating designs at the conceptual level of abstraction (i.e., on robustness diagrams), their leverage to build better software is increased, as is communication with analysts. When analysts only speak requirements, and programmers only speak code, major communication problems can occur.

Figure 3-8: Leverage gained by thinking at a more abstract level

The point of following ICONIX Process is to learn how to manipulate software designs at that conceptual design abstraction level, because that is a very powerful abstraction level to be able to control. “Jedi Master” software designers inherently know how to manipulate the conceptual design abstraction level. Robustness analysis allows this skill to be learned by others.

An example of where robustness diagrams sometimes confound literal-minded programmers is with the message arrows between objects. A literal-minded programmer will naturally interpret these as software messages—for example (leaping ahead to Figure 8-3 the arrow from Get Hotel Name(s) to Create the Tip Text might be interpreted as a method call. Surely, a literal-minded person would naturally assume, there must be a sequence of method calls going Get Hotel Name(s) … Create the Tip Text … Show the Tip Window … and so on. However, the arrows on robustness diagrams simply indicate logical associations.

Tip 

Because you won’t code from robustness diagrams, focus on the logical flow of the use case and worry about the direction of arrows later, in the sequence diagrams.

^[8.]Booch et al., op. cit., p. 9.