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.

UML activity diagrams are the object-oriented equivalent of flow charts and data-flow diagrams from structured development (Gane and Sarson 1979). In UML 1.x, UML activity diagrams were a specialization of UML state machine diagrams, although in UML 2.x they are full-fledged artifacts. UML activity diagrams are used to explore the logic of

1. ■ a complex operation,

2. ■ a complex business rule,

3. ■ a single use case,

4. ■ several use cases,

5. ■ a business process,

6. ■ concurrent processes,

7. ■ software processes.

General Guidelines

Place the Starting Point in the Top Left Corner

A starting point is modeled with a filled circle, using the same notation that UML state chart diagrams use. Every UML activity diagram should have a starting point, and placing it at the top left corner reflects the way that people in Western cultures begin reading. Figure 41, depicting the business process of enrolling in a university, takes this approach. Another good option is to place it at the top center of the diagram.

Include an Ending Point

An ending point is modeled with a filled circle with a border around it. Some people's style is to make ending points optional—sometimes an activity is simply a dead end—but if this is the case, then there is no harm in indicating that the only activity edge (formerly known as a transition) is to an ending point. That way, when someone else reads your diagram, they know that you have considered how to exit these activities.

Models are used by professional developers to communicate their work to project stakeholders and to other developers. The Unified Modeling Language (UML) has been an important part of the software development landscape since its introduction in 1997. We've seen the UML evolve over the years and it is now into its 2.x series of releases. Modeling style, however, has remained constant and will continue to do so. By understanding and following these common modeling style guidelines, you can improve the effectiveness of your models.

I've updated this book to include the new diagrams in UML 2, to use the terminology of UML 2, and to include hand-drawn diagrams. The vast majority of models are drawn on whiteboards and I think that it's time that modeling books, including this one, reflect that reality.

Purpose

This book describes a collection of standards, conventions, and guidelines for creating effective UML diagrams. They are based on sound, proven principles that will lead to diagrams that are easier to understand and work with.

These simple, concise guidelines, if applied consistently, will be an important first step in increasing your productivity as a modeler.

Features

This guide attempts to emulate Strunk and White's (1979) seminal text, The Elements of Style, which lists a set of rules describing the proper application of grammatical and compositional forms in common use within the written English language.

Using a similar style of presentation, this book defines a set of rules for developing high-quality UML diagrams.

An important benefit of the UML is that it is consistent, and part of that consistency is the application of common modeling elements across different diagrams. This chapter describes guidelines for

1. ■ Notes

2. ■ Stereotypes

3. ■ Frames

4. ■ Interfaces

Guidelines for UML Notes

A UML note is a modeling construct for adding textual information—such as a comment, constraint definition, or method body—to UML diagrams. As you can see in Figure 6, notes are depicted as rectangles with the top right corners folded over.

Describe Diagrams with Notes

Ever look at a diagram and not know what it represents? A simple solution is to include a UML note on each diagram that provides a simple and concise description. This is often referred to as a “legend.” In Figure 6 you can see that the name of the system, the purpose of the diagram, and its owner are indicated. It is common also to indicate when the diagram was last updated and the contact information for the owner.

Set a Convention for Placement of Diagram Legends

Placing diagram legends in the same place on all your diagrams increases their usability by making them easy to find. Common spots are one of the corners or the bottom center of a diagram.

Left-Justify Text in Notes

It is common practice to left-justify text in UML notes, as you can see in Figure 6.

Prefer Notes over OCL or ASL to Indicate Constraints

Source code, describing a constraint or processing logic, can be modeled on any UML diagram using a note.

UML object diagrams depict instances and their relationships at a point in time. You create a UML object diagram to

1. ■ explore “real-world” examples of objects and the relationships between them;

2. ■ explain complex relationships between classes to people who find class diagrams too abstract;

3. ■ become input into creating a UML class diagram.

Indicate Attribute Values to Clarify Instances

Figure 52 depicts a UML object diagram, taken from The Object Primer 3rd Edition (Ambler 2004), which explores the relationships between students and seminars. The student objects have been given understandable names, such as John Smith and Sally Jones, which immediately identify them. The seminar objects also have understandable names, such as CSC 100a, but also have attribute values such as Term = “Fall” to clarify which seminar is truly meant.

Prefer Object Names over Attribute Values

Whenever possible try to find a good, understandable name for an object without resorting to indicating attribute values. This makes your object diagrams concise.

Indicate Roles to Distinguish Different Relationships

In Figure 52 you see that it is possible for students to be both teaching assistants and simply students of a seminar; for example, Sarah McGrath is a teaching assistant in CSC 100b, whereas Scott Ambler is a student of that seminar. Identifying roles in this manner can help you to identify different associations between the same classes.

A UML deployment diagram depicts a static view of the run-time configuration of hardware nodes and the software components that run on those nodes. UML deployment diagrams show the hardware for your system, the software that is installed on that hardware, and the middleware used to connect the disparate machines to one another. You create a UML deployment model to

1. ■ explore the issues involved in installing your system into production;

2. ■ explore the dependencies that your system has with other systems that are currently in, or planned for, your production environment;

3. ■ depict a major deployment configuration of a business application;

4. ■ design the hardware and software configuration of an embedded system;

5. ■ depict the physical topology of the hardware/network infrastructure of an organization.

General Guidelines

Indicate Software Components on Project-Specific Diagrams

Figure 49 depicts a UML deployment diagram for a university administration system. This diagram depicts how the major software components that compose a single application are to be deployed into the production environment, enabling the project team to identify its deployment strategy.

Assume That Nodes Are Devices

Figure 49 only indicates that ApplicationServer is a device (a hardware node); the other servers did not include the stereotype. It is common practice to assume that nodes are devices. Did you think otherwise with respect to Figure 49?

Use Concise Notation

Figure 49 is a concise version of Figure 49, which in my opinion is far more useful. Remember Agile Modeling's (Chapter 17) Depict Models Simply practice.

UML communication diagrams, formerly known as collaboration diagrams, are used to explore the dynamic nature of your software. Communication diagrams show the message flow between objects in an object-oriented application, and also imply the basic associations (relationships) between classes. Communication diagrams are often used to

1. ■ provide a bird's-eye view of a collection of collaborating objects, particularly within a real-time environment;

2. ■ provide an alternate view to UML sequence diagrams;

3. ■ allocate functionality to classes by exploring the behavioral aspects of a system;

4. ■ model the logic of the implementation of a complex operation, particularly one that interacts with a large number of other objects;

5. ■ explore the roles that objects take within a system, as well as the different relationships in which they are involved when in those roles.

General Guidelines

Create Instance-Level Diagrams to Explore Object Design Issues

Instance-level UML communication diagrams, such as the one shown in Figure 33, depict interactions between objects (instances). Instance-level diagrams are typically created to explore the internal design of object-oriented software. This by far is the most common style of UML communication diagram.

Create Specification-Level Diagrams to Explore Roles

Specification-level UML communication diagrams, such as the one shown in Figure 37, are used to analyze and explore the roles taken by domain classes within a system. This style of UML communication diagram is not common because most modelers identify roles via UML class diagrams.

Apply Robustness Diagram Visual Stereotypes

Figure 33 is effectively a detailed robustness diagram (Jacobson, Christerson, Jonsson, and Overgaard 1992; Rosenberg and Scott 1999).

When Buchberger's algorithm (1965) became available within the algebraic geometry community, two unrelated results by Macaulay were seen in a different perspective. They are

1. • Macaulay's remark (Lemma 23.3.1 and Corollary 23.3.2) that an ideal I and its monomial ideal T(I) have the same Hilbert function, thus combinatorially allowing us to deduce information on H(T; I);

2. • the notion of H-basis (Definition 23.2.1) which mimics the notion of Gröbner bases using linear forms in place of maximal terms and whose computation was performed by Macaulay (Example 23.7.1) à la Buchberger by computing the syzygies among the leading forms of the bases and lifting them to relations between the basis elements.

The earliest research aimed at computing ideal theoretical problems by applying the Gröbner technology introduced by Buchberger was strongly infiuenced by these ideas of Macaulay; they provided a specific paradigm, which reduced the computational problems for ideals to the corresponding combinatorial problems over monomials. For instance:

1. • the problem of computing the Hilbert function of an ideal I, following Hilbert's argument, is easily reduced to a combinatorical inclusion-exclusion counting of monomials (Corollary 23.4.3);

2. • a deeper analysis and generalization of Macaulay's H-basis computation led Spear and Schreier to formulate and prove the Lifting Theorem (Theorem 23.7.3) which is the basis of the algorithms for computing resolutions.