Composite structure diagrams are an addition to UML 2, although one style used to be referred to as an instance collaboration diagram. Composite structure diagrams are used to

1. ■ depict the internal structure of a classifier (such as a class, component, or use case), including the interaction points of the classifier to other parts of the system;

2. ■ explore how a collection of cooperating instances achieves a specific task or set of tasks;

3. ■ describe a design or architectural pattern or strategy.

There are two basic styles of UML composite structure diagram, the “collaboration style” depicted in Figure 53 from UML 1 and the new “detailed style” of Figure 54. Both diagrams model the same concept, the Persist Object Via Framework architectural strategy (Ambler 2003). Each box represents a lifeline and the dashed oval a collaboration. In the case of Figure 53 the focus is on the overall collaboration required to persist business objects, whereas in Figure 54 the focus is on the individual collaborations required to do so. The diagrams could in fact be combined—the detailed style of diagram could be encircled by a collaboration bubble.

Focus on Object Roles in Collaboration-Style Composite Structure Diagrams

In collaboration-style composite structure diagrams, such as Figure 53, most of the value of the diagram comes in identifying the various roles that lifelines play in the collaboration.

Focus on Collaborations in Detailed-Style Composite Structure Diagrams

In detailed-style composite structure diagrams, such as the one depicted in Figure 54, the value comes from identifying the collaborations between lifelines.

UML component diagrams show the dependencies among software components, including the classifiers that specify them, such as implementation classes, and the artifacts that implement them, such as source-code files, binary-code files, executable files, scripts, and tables. Create them to

1. ■ model the low-level design configuration of your system,

2. ■ model the technical infrastructure (Ambler 1998),

3. ■ model the business/domain architecture for your organization (Ambler 1998).

Component Guidelines

In Figure 47, components are modeled as rectangles with either the text stereotype of «component» or the visual stereotype of a bandage box, as you can see in Figure 47. Components realize one or more interfaces, modeled using the lollipop notation in Figure 47, and may have dependencies on other components or interfaces. As you can see, the Persistence component has a dependency on the Corporate DB component.

Apply Descriptive Names to Architectural Components

Architectural diagrams are often viewed by a wide range of people who may not be familiar with your project. Therefore, component names need to be understandable. For example, most of the components in Figure 47, with the exception of Corporate DB, are named using full words such as Customer and Persistence. The name Corporate DB was used over Corporate Database because that is what it is known as within the company—abbreviations are preferable only when they are in common use.

Apply Environment-Specific Naming Conventions to Detailed Design Components

When you are creating a detailed component model, perhaps to understand the physical configuration of your system, then name your components using environment-specific names.

A UML package diagram depicts two or more packages and the dependencies between them. A package is a UML construct that enables you to organize model elements, such as use cases or classes, into groups. Packages are depicted as file folders and can be applied on any UML diagram, although any diagram that depicts only packages (and their interdependencies) is considered a package diagram. UML package diagrams are in fact new to UML 2, although they were informally part of UML 1—what we called package diagrams in the past were in fact UML class diagrams or UML use-case diagrams consisting only of packages. Create a package diagram to

1. ■ depict a high-level overview of your requirements,

2. ■ depict a high-level overview of your design,

3. ■ logically modularize a complex diagram,

4. ■ organize source code,

5. ■ model a framework (Evitts 2000).

Class Package Diagram Guidelines

Create Class Package Diagrams to Logically Organize Your Design

Figure 28 depicts a UML package diagram that organizes a collection of related classes. In addition to the package guidelines presented later in this chapter, apply the following heuristics to organize classes into packages:

1. ■ Classes of a framework belong in the same package.

2. ■ Classes in the same inheritance hierarchy typically belong in the same package.

3. ■ Classes related to one another via aggregation or composition often belong in the same package.

4. ■ Classes that collaborate with each other a lot often belong in the same package.

Create UML Component Diagrams to Physically Organize Your Design

If you have decided on a component-based approach to design, such as that promoted by Enterprise Java Beans (EJB) or Visual Basic, you should prefer a UML component diagram over a UML package diagram to depict your physical design.

UML state machine diagrams depict the dynamic behavior of an entity based on its response to events, showing how the entity reacts to various events based on its current state. Create a UML state machine diagram to

1. ■ explore the complex behavior of a class, actor, subsystem, or component;

2. ■ model real-time systems.

General Guidelines

Create a State Machine Diagram When Behavior Differs Based on State

If an entity, such as a class or a component, exhibits the same sort of behavior regardless of its current state, then drawing a UML state machine diagram will be of little use. For example, a SurfaceAddress class is fairly simple, representing data that you will display and manipulate in your system. Therefore, a UML state machine diagram would not reveal anything of interest. On the other hand, a Seminar object is fairly complex, reacting to events such a enrolling a student differently depending on its current state, as you can see in Figure 38.

Place the Initial State in the Top Left Corner

An initial state is modeled with a filled in circle, as you can see in Figure 38. Placing an initial state in the top left corner reflects the way that people in Western cultures read. Another good option is to place the initial state at the top of your diagram in the center.

Timing diagrams, which electrical engineers have been using for years, are a new addition to the UML. They depict the change in state or condition of a classifier instance or role over time, often in response to external events. Timing diagrams are often used in the design of embedded software, such as control software for a fuel injection system in an automobile, although they occasionally have their uses for business software too. A UML timing diagram should be created when timing, not sequence, is of critical importance.

General Guidelines

Figure 57 depicts a typical UML timing diagram, showing how a project team progresses through the various high-level stages of a project's life cycle. In this case the team shifts back and forth between four discrete activities/states—Implement, Deploy, Support, and Wait. Several time observations are marked using the format “t=XXXX,” where XXXX is an event or actual time value. A time constraint, {t==0 . .4 weeks}, indicates the potential length of time that the initial implementation efforts may take.

It is interesting to note that Figure 57 could actually be considered a value stream map (Poppendieck and Poppendieck 2003) because it indicates the amount of time that the team spends adding value (working in the first three states) in comparison to the time wasted waiting.

Draw a Continuous Timing Diagram for Analog Values

Figure 58 shows how you would model a continuous stream of analog values, in this case the changing percentage over time of decided voters in an election.

Interaction overview diagrams are new to UML 2. They are a variant of an activity diagram where each bubble on the diagram represents another interaction diagram. UML interaction overview diagrams are used to

1. ■ overview the flow of control within a business process;

2. ■ overview the detailed logic of a software process;

3. ■ connect several diagrams together.

Figure 55 depicts an interaction overview diagram that models how the logic for enrolling in a seminar could be implemented.

Reference Other Diagrams, Don't Depict Them

Although it is very interesting to depict a diagram within another diagram, as you see with the two diagram frames in Figure 55, the reality is that you rarely have the drawing space to do such a thing. A more realistic version of the diagram is presented in Figure 56 that uses just interaction use frames to refer to operations implemented by various objects.

Don't List Lifelines

Both Figure 55 and Figure 56 list the lifelines that appear within the frame—Figure 56 lists only two because it doesn't depict as much detail as Figure 55. In either case the information is superfluous; you can gain it from looking at the diagram.

Agile Modeling (AM) (Ambler 2002) is a chaordic (Hock 2000), practice-based methodology for effective modeling of software-based systems. The AM methodology is a collection of practices guided by principles and values that can be applied by software professionals on a day-to-day basis. AM is not a prescriptive process. It does not define detailed procedures for creating a given type of model, but it does provide advice on how to be effective as a modeler. It's not hard and fast—think of AM as an art, not a science.

Values

The foundation of AM is its five values, the first four adopted from eXtreme Programming (XP) (Beck 2000):

1. ■ communication,

2. ■ courage,

3. ■ feedback,

4. ■ simplicity,

5. ■ humility.

Principles

The principles of AM, which are based on its values, define the basis for its practices. The principles are organized into two collections: the core principles, which you must fully adopt to be able to claim you are “agile modeling,” and the supplementary principles, which support the core. Table 10 lists the principles of AM.

Practices

The practices of AM define effective techniques for modeling. As with the principles, the practices are organized into two groups, core and supplementary. Table 11 lists the practices of AM.

UML class diagrams show the classes of a system, their interrelationships, and the operations and attributes of the classes. They are used to

1. ■ explore domain concepts in the form of a domain model,

2. ■ analyze requirements in the form of a conceptual/analysis model,

3. ■ depict the detailed design of object-oriented or object-based software.

A class model comprises one or more class diagrams and the supporting specifications that describe model elements, including classes, relationships between classes, and interfaces.

General Guidelines

Because UML class diagrams are used for a variety of purposes—from understanding your requirements to describing your detailed design—you will need to apply a different style in each circumstance. This section describes style guidelines pertaining to different types of class diagrams.

Identify Responsibilities on Domain Class Models

When creating a domain class diagram, often as part of your requirements modeling efforts, focus on identifying responsibilities for classes instead of on specific attributes or operations. For example, the Invoice class is responsible for providing its total, but whether it maintains this as an attribute or simply calculates it at request time is a design decision that you'll make later.

There is some disagreement about this guideline because it implies that you should be taking a responsibility-driven approach to development. Craig Larman (2002) suggests a data-driven approach, where you start domain models by identifying only data attributes, resulting in a model that is little different from a logical data model.

A UML use-case diagram shows the relationships among actors and use cases within a system. They are often used to

1. ■ provide an overview of all or part of the usage requirements for a system or organization in the form of an essential model (Constantine and Lockwood 1999, Ambler 2004) or a business model (Rational Corporation 2002);

2. ■ communicate the scope of a development project;

3. ■ model the analysis of usage requirements in the form of a system use-case model (Cockburn 2001).

A use-case model comprises one or more use-case diagrams and any supporting documentation such as use-case specifications and actor definitions. Within most use-case models, the use-case specifications tend to be the primary artifact, with UML use-case diagrams filling a supporting role as the “glue” that keeps your requirements model together. Use-case models should be developed from the point of view of your project stakeholders and not from the (often technical) point of view of developers.

Use-Case Guidelines

A use case describes a sequence of actions that provide a measurable value to an actor. A use case is drawn as a horizontal ellipse on a UML use case diagram, as you can see in Figure 14.

Begin Use-Case Names with a Strong Verb

Good use-case names include Withdraw Funds, Register Student in Seminar, and Deliver Shipment because it is clear what each use case does. Use-case names beginning with weak verbs such as “process,” “perform,” and “do” are often problematic.

One of Agile Modeling's (AM) practices (discussed in Chapter 17) is Apply Modeling Standards, the modeling version of Extreme Programming (XP)'s Coding Standards (Beck 2000). Developers should agree to and follow a common set of standards and guidelines on a software project, and some of those guidelines should apply to modeling. Models depicted with a common notation and that follow effective style guidelines are easier to understand and to maintain. These models will improve communication internally within your team and externally to your partners and customers, thereby reducing the opportunities for costly misunderstandings. Modeling guidelines will also save you time by limiting the number of stylistic choices you face, allowing you to focus on your actual job – to develop software.

When you adopt modeling standards and guidelines within your organization, your first step is to settle on a common notation. The Unified Modeling Language (UML) (Object Management Group 2004) is a good start because it defines the notation and semantics for common object-oriented models. Some projects will require more types of models than the UML describes, as I show in The Object Primer 3/e (Ambler 2004), but the UML will form the core of any modern modeling effort.

Your second step is to identify modeling style guidelines to help you to create consistent and clean-looking diagrams.

The guidelines presented in this chapter are applicable to all types of diagrams, UML or otherwise. The terms “symbols,” “lines,” and “labels” are used throughout:

1. ■ Symbols represent diagram elements such as class boxes, object boxes, use cases, and actors.

2. ■ Lines represent diagram elements such as associations, dependencies, and transitions between states.

3. ■ Labels represent diagram elements such as class names, association roles, and constraints.

Readability Guidelines

Avoid Crossing Lines

When two lines cross on a diagram, such as two associations on a UML class diagram, the potential for misreading a diagram exists.

Depict Crossing Lines as a Jump

You can't always avoid crossing lines; for example, you cannot fully connect five symbols (try it and see). When you need to have two lines cross, one of them should “hop” over the other as in Figure 1.

Avoid Diagonal or Curved Lines

Straight lines, drawn either vertically or horizontally, are easier for your eyes to follow than diagonal or curved lines. A good approach is to place symbols on diagrams as if they are centered on the grid point of a graph, a built-in feature of many computer-aided system-engineering (CASE) tools. This makes it easier to connect your symbols by only using horizontal and vertical lines. Note how three lines are improved in Figure 2 when this approach is taken. Also note how the line between A and C has been depicted in “step fashion” as a line with vertical and horizontal segments.

UML sequence diagrams are a dynamic modeling technique, as are UML communication diagrams. UML sequence diagrams are typically used to

1. ■ Validate and flesh out the logic and completeness of a usage scenario. A usage scenario is exactly what its name indicates—the description of a way that your system could be used. The logic of a usage scenario may be part of a use case, perhaps an alternate course; one entire pass through a use case, such as the logic described by the basic course of action or a portion of the basic course of action plus one or more alternate scenarios; or a pass through the logic contained in several use cases, such as when a student enrolls in the university and then immediately enrolls in three seminars.

2. ■ Explore your design because they provide a way for you to visually step through invocation of the operations defined by your classes.

3. ■ Give you a feel for which classes in your application are going to be complex, which in turn is an indication that you may need to draw state machine diagrams for those classes.

4. ■ Detect bottlenecks within an object-oriented design. By looking at what messages are being sent to an object, and by looking at roughly how long it takes to run the invoked method, you quickly get an understanding of where you need to change your design to distribute the load within your system. Naturally, you will still want to gather telemetry data from a profiling tool to detect the exact locations of your bottlenecks.