ICONIX Process in a Nutshell

In this section, we describe the process itself. In a nutshell, ICONIX Process describes how to get from use cases to code reliably, in as few steps as possible.

Figure 3-3 shows how the different activities in ICONIX Process fit together.

Figure 3-3: ICONIX Process

ICONIX Process can be broken down into the following steps (the items in bold are the concrete modeling activities that you perform at each step):

• Step 1: Identify your real-world domain objects (domain modeling).

• Step 2: Define the behavioral requirements (use cases).

• Step 3: Perform robustness analysis to disambiguate the use cases and identify gaps in the domain model.

• Step 4: Allocate behavior to your objects (sequence diagrams).

• Step 5: Finish the static model (class diagram).

• Step 6: Write/generate the code (source code).

• Step 7: Perform system and user-acceptance testing.

If you follow this process to the letter for your analysis and design modeling activities, then your project will stand a good chance of meeting the customer’s requirements—and doing so within a reasonable time frame.

As we walk through each of these steps in detail in the sections that follow, we’ll note four key milestones that tend to look good on a project plan (they’re also useful planning checkpoints, as they provide key stages where you can both say and demonstrate that “this XYZ work is done, so now we’re moving on to the next stage”).

• Milestone 1: Requirements Review

• Milestone 2: Preliminary Design Review

• Milestone 3: Detailed/Critical Design Review

• Milestone 4: Delivery

Step 1: Identify Your Real-World Domain Objects

Getting this step right is possibly the most important part of the whole project, because it establishes a solid foundation upon which absolutely everything else in the project (requirements, design, code, and so forth) is built.

Tip 

As important as it is to spend time getting the domain model right, it shouldn’t stall the rest of the project. Throughout the analysis and design activities, we’ll keep coming back to the domain model to add to it and correct it. The domain model evolves over time along with our understanding of the problem domain.

This step can be further subdivided into the following steps:

1. Identify your real-world domain objects and the generalization and aggregation relationships among those objects. Start drawing a high-level class diagram.

2. If it’s feasible, do some rapid prototyping of the proposed system, or gather whatever substantive information you have about the legacy system you’re reengineering.

When this step is finished, you should have a reasonably correct domain model, which everyone on the project (the customer, the programmers, the analysts, the testers, and even the end users) can share and use as a common vocabulary. The domain model will continue to evolve and grow (and hopefully be whittled down to something simpler that still captures the business domain) as the project progresses.

Note 

It’s worth emphasizing that in ICONIX Process, we begin with a domain model and then write the use cases in the context of the domain model (further evolving the domain model as we go). Other processes advise starting with the use cases and then creating the domain model, but there are good reasons to do it the ICONIX way, notably that the domain model provides a common vocabulary for the use cases to be written against, thus avoiding ambiguous naming (using different names for the same thing) in the use case text.

The domain model is a preliminary guess at the static model (class diagrams) based strictly on problem-domain entity classes—no solution-space stuff. No attributes or operations are shown on the classes.

The domain model contains real-world things and concepts related to the problem that the system is being designed to solve. When we create a domain model, we’re creating a representation of the objects and actions that form the business and are focused on the problem that the project is attempting to solve. The initial domain model that you create for any project will never be perfect. It will evolve throughout the project as your understanding of the problem domain evolves.

Tip 

As you identify patterns and similarities in the domain model (and resolve ambiguities), you might suddenly discover ways of representing the same information from the business domain in a simpler, less ambiguous form. When this happens, don’t hold back: go ahead and update the domain model, because the discovery of a simpler model could well lead to further improvements.

How do you actually identify objects to go in the domain model? There are a number of techniques, the most important of which is simply to use your own experience and judgment. A good starting point if you’re really stuck, however, is to use the grammatical inspection technique:^[6.] quickly pass through the available relevant material (requirements, business glossaries, and so forth), highlighting nouns and verbs as you go. Note that the relevant material should also include your own interviews with the customer and end users of the system. Often these discussions help more than anything else to resolve ambiguities and identify further domain objects.

After refining the lists as work progresses, you should find that

• Nouns and noun phrases become classes and attributes.

• Verbs and verb phrases become operations and associations.

• Possessive phrases indicate that nouns should be attributes rather than classes.

These items represent only a general rule, of course (though a darned useful one). You might well find, for example, that some verbs eventually become objects rather than operations (particularly if you’re modeling a business process, or if you’ve identified a manager, or controller, class).

You should continue to iterate and refine the domain model, but this doesn’t mean that you should keep grinding nouns and verbs indefinitely. The goal is to build a glossary of object names that will serve as the nouns, as appropriate, within your use case text.

It’s worth establishing a time budget for building your initial domain model (e.g., restrict it to a collaborative workshop taking no more than a morning, or even just a couple of hours). The domain model is important, but you don’t want it to prevent the remainder of the project from ever getting started! You can generally find the most important 80% of your domain classes within a couple of hours—and that’s good enough to get going. You don’t have to get it perfect, because you’ll discover the remaining classes as you work through the use cases.

Step 2: Define the Behavioral Requirements

As you’ve probably gathered by now, the behavioral requirements in an ICONIX project are defined by use cases. The use cases expand on the high-level requirements (discussed in the previous step) and define how the system will behave in terms of user interactions. As we’ll discuss later in this book, this step benefits from being augmented with detailed interaction design (especially persona analysis; see Chapter 12).

This step can be further subdivided into the following steps:

1. Identify your use cases using use case diagrams.

2. Organize the use cases into groups. Capture this organization in a package diagram.

3. Allocate functional requirements to the use cases and domain objects. (This step is optional depending on the formality of the project.)

4. Write descriptions of the use cases (i.e., basic courses of action that represent the mainstream and alternative courses for less frequently traveled paths and error conditions).

Tip 

Most projects will begin with a list of high-level requirements. These requirements define what the customer wants from the project, and they should in turn be based on a definition of the problem. If all this can be based on the domain model, then so much the better. Often, however, the requirements will be handed down to your team from upon high, and it’s left to you to make sense of them and produce a set of use cases. In such cases where there’s ambiguity, your only recourse is to ask questions, and lots of them—and keep asking them until you get answers that resolve the ambiguity.

How do you know when you’ve finished use case modeling? You’re ready to move to the next phases of the development process when you’ve achieved the following:

• You’ve built use cases that together account for all of the system’s desired functionality.

• 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 the precedes and invokes constructs (or whichever constructs you generally prefer using).

Milestone 1: Requirements Review

Step 3: Perform Robustness Analysis to Disambiguate the Use Cases and Identify Gaps in the Domain Model

This is the final analysis step in the project. As you’ll see later in this chapter, robustness analysis plays a key role in ICONIX Process. At its core is the robustness diagram (see Figure 3-4).

Figure 3-4: Example robustness diagram

Robustness analysis involves working through the text of a use case and taking a preliminary peek at how you might design some software to implement a given use case, using the objects you’ve discovered up to this point. One of the main purposes of this activity is to discover when you don’t have all the objects you need, and then add them to your class diagram.

The robustness analysis step is further subdivided into the following steps:

1. Draw robustness diagrams. For each use case

   1. Identify a first cut of objects that accomplish the stated scenario. Use the UML Objectory stereotypes (see Figure 3-5).

      
      Figure 3-5: Robustness analysis stereotypes

   2. Update your domain model class diagram with new objects and attributes as you discover them.

   3. Update (disambiguate) the use case text so that it matches the robustness diagram.

2. Finish updating the class diagram so that it reflects the completion of the analysis phase of the project.

Milestone 2: Preliminary Design Review

Tip 

Though not essential, a useful trick is to highlight alternative scenario stuff on the robustness diagram in a different color. This makes it easier to read through and follow along with the basic scenario, and it helps you ensure you’ve covered all the alternatives.

Ivar Jacobson introduced the concept of robustness analysis to the world of OO in 1991. Robustness analysis involves analyzing the narrative text of each of your use cases and identifying a first-guess set of objects that will participate in the use case, and then classifying these objects into the following three object types:

• Boundary objects, which actors use in communicating with the system.

• Entity objects (also referred to as entities), which are usually objects from the domain model.

• Control objects (also referred to as controllers), which serve as the “glue” between Boundary objects and Entity objects. Sometimes these are real Control objects, but most of the time they simply represent verb placeholders for functions.

This simple but highly useful technique serves as a crucial link between analysis (the what) and design (the how). We’ll walk through several examples of robustness analysis later in this book.

These three object types translate well into the Model-View-Controller (MVC) design pattern,^[7.] which is used heavily in both client-server and GUI development. Entity objects are delivered by the Model, Boundary objects form the View, and Control objects form the Controller. For example, in a three-tier web application, a Boundary (or View) object could be a JSP page (sometimes also referred to as the presentation layer); the entities (i.e., the data) would be served up by a database, usually via a business object layer; and the Control object that binds the whole enchilada together would be provided by a business logic layer housed in an application server.

In a rich-client GUI application, a Boundary (or View) object could be a table or combo box component (e.g., in Java Swing, a JTable or JComboBox), the Model object would be the data model (e.g., DefaultTableModel) that serves up the entities to be displayed by the component, and the Control code would handle the UI events (e.g., scrolling up and down through the table) to determine which data from the model the view needs to display.

As projects grow in functionality (or in other ways, such as the number of users accessing the deployed system concurrently), the architecture must scale up to meet the challenge. This often leads to a more complex architecture, typically with functionality divided into separate layers (e.g., different areas of application logic might be separated out into different layers). This can be viewed as an extension of the Boundary-Control-Entity (BCE) architecture (or the MVC architecture), so ICONIX Process can still readily be applied to more complex architectures (i.e., the process can scale up to meet the demands of your project).

Step 4: Allocate Behavior to Your Objects

This step is where the design phase of the project begins. Our main diagram of choice for this step is the sequence diagram (see Figure 3-6), although you might also use additional diagrams and activities (such as state diagrams, activity diagrams, or unit tests following a strict test-driven methodology; see Chapters 12) as you see fit.

Figure 3-6: Example sequence diagram

This step is further subdivided into the following steps for each use case:

1. Identify the messages that need to be passed between objects and the associated methods to be invoked.

2. Draw a sequence diagram with use case text running down the left side and design information on the right.

3. Continue to update the class diagram(s) with attributes and operations as you find them.

If you’re not allocating operations to classes on the sequence diagram, you’re ignoring its primary mission in life.

For each use case, you create one sequence diagram. This is an important point to remember, because you don’t want to end up getting bogged down with many diagrams just to map out the interaction in a single use case. Doing so would give you a nasty case of analysis paralysis so, even if you have multiple alternative scenarios on your use cases, put everything on the one sequence diagram.

This is the reason for the two-paragraph rule on use case text: you can fit the whole thing on one sequence diagram. The net result of this approach is that it prevents the diagrams from becoming too fragmented. It means you can validate that you’ve addressed the whole use case by reading a single diagram. Too many fragments make it hard to be sure you got all of the use case.

Modeling Question 

The basic path and all the alternative paths are shown on one sequence diagram. But what happens if you have 20 alternative paths? You’re almost definitely looking at more than one use case if it has 20 alternative courses of action. You should split up the use case. If your alternatives start having their own alternatives, for example, it’s time to split ’em off.

Step 5: Finish the Static Model

As the title of this step suggests, the key design artifact here is the static model, which is made up of one or more class diagrams (see Figure 3-7).

Figure 3-7: Example class diagram for the mapplet project presented in Part 2

This step is further subdivided into the following steps:

1. Add detailed design information (e.g., visibility values and patterns).

2. Verify with your team that your design satisfies all the requirements you’ve identified.

Milestone 3: Detailed/Critical Design Review

The static model is the grittier, more detailed version of the domain model, and it contains more implementation details. The static model has detailed class diagrams (perhaps even reverse engineered from the source code, but not necessarily) that are at a very detailed abstraction level and match the sequence diagrams.

Tip 

In an ideal world, the operations on the classes on the static model should have gotten there by message arrows drawn on sequence diagrams, and the source code headers should have been generated from these class diagrams. Over successive iterations, the UML and as-built models would start moving closer together (converging) so that the use case robustness sequence classes code progression is really being followed. Realistically, this doesn’t always happen, but if the team can demonstrate that the code meets the written requirements and the use cases, then that may be “good enough” even if it isn’t always optimal.

MODELING QUESTION: SHOULD WE REUSE THE DOMAIN MODEL DIAGRAM AND SIMPLY KEEP ADDING TO IT UNTIL WE HAVE OUR STATIC MODEL?

If you know that your project is going to go through only one release (or a couple of releases at most), this approach serves nicely. However, in an agile project with lots of short releases and with domain modeling activities at the start of each release, it pays to keep separate diagrams for the domain model and class diagrams. The class diagram still grows and evolves from the original domain model (this approach is fundamental to ICONIX Process), but the diagrams are kept separate.

The domain model reflects our current understanding of the business domain (i.e., it’s an analysis-level artifact), whereas the fleshed-out class diagrams (there may be several) are collectively a detailed design artifact. As our understanding of the business domain evolves, we need to be able to quickly update and maybe also refactor the domain model, without getting slowed down by having to consider design details from previous iterations (at least not yet—that comes when we get to the design stage).

Of course, this means that you have an extra diagram to update, but it’s a trade-off. The benefit is that it’s much easier to keep the domain model up to date, and it’s easier to read (because it’s uncluttered by design details and records of design decisions).

If the domain model and the class diagram are the same diagram, it’s also more difficult to update the domain model in light of new business understanding, because you’re in effect modifying the detailed design without going through all the intermediate steps to get there (robustness analysis, sequence diagrams, and so forth).

Step 6: Write/Generate the Code

This step is, of course, where the programmers take the design and start to code from it. The programmers should have been involved in all the design steps (ideally the designers are also the programmers), so that the design has some grounding in the reality of the technologies in which the system will be implemented.

This step is subdivided into the following steps:

1. Write/generate the code.

2. Perform unit and integration testing.

If you are combining ICONIX Process with a test-driven approach (see Chapter 12), then the unit tests will be written before the code. An important point here is that the programmers are doing their own testing, including integration testing.

Tip 

It pays to have integration testing performed by a different programmer from the one who coded the module being tested, in addition to the testing performed by the original programmer. This often catches more defects, and it has the added benefit that each programmer gains more exposure to the rest of the project.

Step 7: Perform System and User-Acceptance Testing

For this stage, a different group from the programming team (ideally a separate QA team) performs system and user-acceptance testing, using the use cases as black-box test cases for the latter.

Milestone 4: Delivery

^[6.]Kurt Derr, Applying OMT: A Practical Step-By-Step Guide to Using the Object Modeling Technique, (New York: Cambridge University Press, 1995).

^[7.]See http://java.sun.com/blueprints/patterns/MVC.html.