Making Diagrams Useful Not Archival

John D. McGregor

I have a running debate with some of the other faculty members in my department. They want me to publish in "archival" research journals and I want to publish where people actually read the papers! All too often, the diagrams and models produced during a project are treated as archival documentation. They are created and then ignored or, in some cases, not created at all. In some cases they are even created after the code has been written.

Some of the projects with which I consult are large. That is two hundred plus developers who are all working together to manufacture a single product. The quality of the analysis and design models is always critical to the overall quality of the product. With hundreds, or more likely thousands, of classes, the models become critical to the technical quality and productivity of the project. The Unified Modeling Language (UML) defines a number of diagrams that are used to create models. The typical project creates models at a number of points in the software life cycle. The result can be an overwhelming number of diagrams. In this column I want to discuss some ideas for organizing the various diagrams that together comprise a UML analysis or design model and how to control the evolution of these models.

The goal of model building is to allow the development team to think through the concepts and relationships needed for the complete system. To be effective, the model must have the same scope as the completed system although not at the same level of detail. To be useful, the model must be MUCH easier to construct than the code is to write. UML provides a notation that achieves these requirements and that is what I will use in this column; however, a number of modeling languages achieve basically the same goal.

A model for a system is considered to be of high quality if it facilitates the development of the implementation for that system. The model must be a correct representation or effort is expended on code that must be altered later. The pieces of the model must be consistent or developers working independently will not be able to integrate their work. The model must be sufficiently complete or some of the required functionality will be coded without first being modeled. For more on the three Cís of model validation see [1].

There is a dynamic tension between producing a complete, correct and consistent model and supporting the needs of the project. These needs include information for tracking progress and for coordinating the concurrent activities of numerous small development teams. This is particularly difficult if the teams are not co-located. (that is a technical term meaning the teams are separated by miles, oceans or, even worse, organizational boundaries.)

Large projects have special problems because of their scale. The hierarchy of class/package is not sufficient to divide the set of classes into a manageable number of diagrams with a reasonable number of classes in each diagram. Additional rationales for subdividing diagrams are needed. Below I will provide some suggestions based on the types of relationships involved.

I donít intend to prescribe an exact set of diagrams that should be used in every situation. I am always concerned that such a prescription makes the diagrams look like yet another process "hurdle" to be crossed off the schedule when completed. I view these diagrams as tools to help me think about the problem or about its solution. Often if a student or a client asks me a question, I draw a UML diagram to help develop and communicate my answer. I do this because the diagram helps me visualize the design not because of some requirement. I intend to describe ways to make the diagrams contribute to the quality of the project but I will not define a set of diagrams that "must" be created.


The Diagrams

The class diagram is central to the UML modeling process. It is usually the first one built in each model. It is the definitional diagram [2] that provides a vocabulary used in the other diagrams. The class diagram defines the state attributes and method signatures for each class. It also specifies the relationships between classes.

The remaining diagrams illustrate the operational semantics of the entities defined in the class diagram. The message sequence diagram captures a single path through an algorithm while the activity diagram illustrates a complete algorithm with all the paths and any concurrency. The state diagram integrates all of the modifier methods for a class into a diagram that illustrates all possible sequences of method invocation. The deployment diagram describes the distribution across processors of the objects that participate in the algorithms.

The diagrams do serve as documentation; however, their strength is in support of the active development process. Among the most productive consulting sessions that I have with developers are those where we actively create or modify diagrams in "real time". They establish a common vocabulary and provide a useful visualization. Using a CASE tool and projection equipment allows the entire team to participate and makes the session even more valuable since the diagrams are captured as the session progresses. On projects where code is generated automatically by the CASE tool, this is particularly productive.

The Models

In the parlance of UML, diagrams are aggregated to create models. The diagrams included in each model vary depending upon the development phase for which the model is intended and the level of detail that the developers wish to represent. Table 1 shows the diagrams that are typically used for each model.

Smaller projects have less need to model specific details than do large projects. A small development team works more closely and has less need to have formal communication. The projects that we consult with that have hundreds of developers who are located at sites in different states or even different countries need a standardized, unambiguous means of communicating with each other. These large projects often have a need to communicate with more diverse audiences and hence should build comprehensive models.

The level of detail to which a project models, e.g. create pseudo-code for each method, will also vary depending upon the purpose of the model and the development process. Early analysis models will have less detail than the application analysis model and much less detail than the detailed design model. Projects that will generate code directly, and automatically, from the model will need a very fine-grained level of detail. A highly iterative process with small increments will require fewer and less detailed models than a process with longer iterations.


Table 1: Diagrams by Development Phase


Use Case













Domain Analysis






Application Analysis







Architectural Design







Component Construction







System Integration







System Test








Role of the Architecture

The architecture for a software system defines the basic operational structure that organizes the individual objects. This structure also provides a framework for the numerous operational diagrams that are drawn to capture the details of the analysis and design information. Each architectural unit is as loosely coupled to other units as possible. This provides a natural division for definitions, designs and work assignments.

One basis for dividing large operational diagrams such as interaction diagrams is to limit each diagram to the internals of some architectural unit. The other units with which this unit interacts are treated as black boxes with no internal details given. This particularly is useful if the system is distributed over multiple processors.

Limit operational diagrams to the scope of a single architectural unit.

One consequence of this rule is increased attention to interfaces, in this case at the architectural level. Most team assignments result in the publication of an interface to the rest of the teams at the same level and the construction of diagrams describing the internals of that scope.


Scope of diagrams

Each diagram should have a clearly specified and logical scope. In some cases this is simple. A state diagram often represents the transitions of a single class. Where that is not the case, a state diagram should represent the state of a group of classes that are identified as a cluster by being combined on a single class diagram. As I will discuss later, some tools support this correspondence by associating related diagrams.

Label each diagram with the appropriate scope.

For example, the diagram in Figure 1 has the title: Analysis Model for the PCS Package. The "PCS Package" phrase indicates the scope of the diagram.

Message sequence diagrams, used to show scenarios, and activity diagrams, that show complete algorithms, should have clearly defined, logical beginning and ending points. A path through the system could be traced, and represented in a message sequence diagram, from the start of execution of a program to its termination for a specific set of data. This is seldom useful. Rather the scope of the typical diagram is usually one step beyond the developerís (or teamís) development scope. That is, a team will usually include messages their object sends to objects whose classes are defined by other teams, but they do not represent messages sent by that object to others.

One factor that effects the appropriate scope is whether the developers are following the "large" class approach or the "small" class approach. Developers new to object orientation often tend to confuse a class with a module and create very large classes that exhibit low cohesion. In that case, showing all the associated classes for one class may be sufficient information for one diagram. Experienced developers, and particularly those who matured in the paradigm using pure object-oriented languages, tend to develop smaller classes. In this case a single class diagram that shows all the classes in one package may contain sufficient information. The grouping for a diagram should be logical. A diagram that shows half of the classes in a package would not be as useful as a more crowded one that includes all of the classes from that package.

It is important to note that operational and definitional diagrams have very different ways of defining scope. Operational diagrams are scoped based on operational boundaries such as physical processors or operating system processes. A single definition may obviously define a concept for which instances appear on multiple processors or in multiple processes. Definitional diagrams are scoped by semantic relationships. A package is a set of semantically related classes and is often the appropriate scope for a definitional diagram. Below I will describe some of these relationships that can be used to scope a diagram.

Depth of diagrams

The depth of a diagram should correspond to a logical level of detail used in the system development process and should be clearly denoted for each diagram. For example, a message sequence diagram can be used to represent scenarios from use cases that only mention each method that will be invoked or it can illustrate the details of individual methods. In the domain analysis model the message sequence diagrams will contain only domain-level concepts. A developer reading this diagram may think that the diagram is incomplete or inaccurate while to a domain expert the diagram seems perfectly correct.

Some information about depth may be implicit because it is defined in the projectís documentation plan for all diagrams. For example, it is usually the case that the details of library classes that are not being developed by the current project are not shown on any diagram. They are treated as black boxes.

Diagrams should only contain information appropriate to the specified depth. Often a domain-level message sequence diagram will be elaborated to produce a more detailed design-level diagram in later phases of development. The elaborated diagram should be maintained as a separate diagram unless the CASE tool provides a configuration management facility for elements in diagrams. Failure to do this will result in confusion when the domain model is revisited in the next iteration. However, these two diagrams should be related through some device so that modifications to the domain-level diagram will be propagated to the application-level diagram.

Label each diagram with the appropriate depth.

For example, the diagram in Figure 1 has the title: Analysis Model for the PCS Package. The "Analysis model" phrase indicates the depth of detail the model user can expect from that diagram.

Providing context within a single diagram

I once spent a day listening to the reports of one development team after another. Each team showed a class diagram containing the classes that they were defining and talked about the relationships between them. At the end of the day when the project leader asked my opinion of the state of the project I replied that I didnít have a clue! Why? Because each teamís diagram showed only their classes. The dependencies with other teamsí classes were not shown (and you know there had to be some). Once the teams began the exercise of identifying these dependencies many deficiencies were discovered in the diagrams.

Include classes upon which your classes have a direct dependency.

Below I will define a scheme that creates a series of layers in a model. In this case, the association class diagram, which I will explain below, should contain the dependencies on the developerís classes.

Many CASE tools support this by allowing the class box to be collapsed so that only the class name shows. The classes upon which my class depends can be shown in collapsed form while classes I am developing can be shown in full detail. This frees up screen real estate and focuses attention on my work.

Coupling and cohesion for diagrams

Coupling and cohesion are time-honored measures of program quality and can be applied to diagrams as well. For a class diagram, achieving loose coupling means that there are a minimum number of dependencies between classes included in the diagram and those that are not included in the diagram. This can be stated as:

Any class, upon which many classes in the diagram depend, will be included in the diagram.

At the same time, high cohesion is achieved by only including classes that exhibit the relationship being recorded in the diagram. For example, if the class diagram is showing the classes for the composed objects within class A, only classes that provide objects for Aís composition should be shown on the diagram.

Any class included in the diagram should be related to some other class in the diagram by the relationship being illustrated.

Arranging Diagrams

There are several arrangements that are useful for UML diagrams. There is the sequencing based on dependencies. I create three types of class diagrams based on the type of relationship being illustrated: association diagrams, composition, and inheritance diagrams. The association diagram is the central diagram. It contains the root classes of inheritance families and captures the peer-to-peer associations between classes. Following the guidelines given earlier, the associations are limited to those within a single package or other semantic grouping.

The inheritance class diagram contains all the subclasses that belong to an inheritance family. This reduces clutter in the main class diagram. It also reinforces the notion that when you are considering the design of an interaction between two root level classes you should not have to know anything about any of the subclasses. This diagram also facilitates the management of overridden methods among the subclasses.

The composition class diagram presents the composing class and all of its components. That is, each compositional diagram is organized around a single class. The remaining classes in the diagram represent attributes of the focal class. Note that these attributes are composed as opposed to the less restrictive aggregation.

This arrangement is limited to the diagrams within a single model. As you see in Figure 1, I like to think of the associational diagram on one level and the inheritance and compositional diagrams as one level below that diagram. This partially reflects the order in which the diagrams are created. The associational diagram is created first, followed by the other two. It also reflects the logical dependencies among classes. This figure also illustrates that the package diagram should be thought of as a layer above the associational diagrams and as encapsulating a number of such diagrams.

Figure 1: Analysis model for the PCS Package


A second arrangement is the layering that results from increasing the level of detail provided by the progressively more comprehensive models. This ordering is usually between similar diagrams in different models. For example, the state diagram for a domain class will have high-level public states in the domain analysis model but that same diagram in the class design model will add some private transitions and states. Figure 2 shows the successive layers of detail for a state model.

This is a relationship among diagrams that is particularly important for effective development. In iterative development, models are created in the order of increasing detail, but these models are revisited on successive iterations. The additional information added to diagrams in the more detailed design phases is distracting when returning to the more conceptual, less detailed, analysis phases. By creating, and maintaining, layered models of increasing detail, the development team can access the level of information that will be helpful. CAD tools provide this facility by allowing the definition of multiple layers. These layers can be made visible or invisible depending upon current needs.

As we progress from domain analysis to application analysis and on to design, the previous model is modified to produce the next model. The domain analysis models, for all of the domains involved in the system, are "pruned" of concepts not required in the current application. But these concepts are still a part of the domain model. There is this same type of relationship between each two levels of models.




Figure 2: Added Detail in Diagrams


Finally, there is a part/whole relationship between some diagrams. An activity diagram illustrates all aspects of an algorithm. Message sequence diagrams are used to illustrates a single path of execution. The activity notation can be used at a high level to give a view of a complex task with accompanying message sequence diagrams providing the details of each possible path.

Version control in an iterative, incremental world

In this section I want to discuss a problem arising from the orderings discussed in the previous section. The problem is the effort required to maintain a number of levels of models (analysis, design, etc) in the multiple versions produced by successive iterations. CASE tool vendors simply have not addressed this issue adequately.

Most tools do not support the versioning of models and particularly across multiple dimensions. Either each diagram in Figure 2 is a separate diagram in the drawing program or there is one diagram that supports multiple views. It would be useful to be able to tag each element (state, classes, relationships, methods and attributes) in a diagram with the models to which it belongs. That means an entire class could appear in the domain model but not the application analysis model or that a class might not be present in the application analysis model but become visible in the detailed design model. Likewise a method or attribute could be tagged to appear or not.

This is a different requirement from the feature where attributes and operations can, as a group, be made visible or invisible. Allowing the visibility of each attribute and operation to be controlled individually would allow the developer to produce a number of useful views from the database of specifications and definitions. If this feature were available, then a developer could use the projectís version control system to handle diagrams. By versioning the database all of the diagrams are automatically versioned.

Currently, the developers must either create each diagram for each model by hand thereby creating "versions" of the models manually or they reuse a single diagram in several models and ignore the "extra" information that does not pertain to the activity that they are currently performing. The developers should make initial changes to the "highest level" model in which the change applies. Then the developer must propagate those changes manually into the lower level models. "Highest" may mean earliest development phase or it may refer to the model of least detail or even the highest in a hierarchical series of models.

The highest level at which the initial changes are made indicates at a minimum where the next iteration should begin. For example, suppose that a change is made in an element that is present in the application analysis model. Then the next iteration should at least begin at that application analysis level. Other considerations might indicate the need to go even "higher" in the levels of abstraction, all the way back to the domain model.


So once again, why discuss this in a column devoted to Quality Assurance? Improving the quality of the underlying models is a much more effective means of improving the quality of the product than trying to find defects in individual lines of code. A project should provide a clear set of guidelines for each development team to follow that will lead to individual team models that easily integrate producing an application model that provides an accurate, useful means of communication and documentation. By dividing large models into logical groupings, even large design spaces are reduced to manageable proportions. By layering diagrams based on orderings that parallel the sequence of development and on the type of relationship being represented, information is easier to understand, remember and evaluate. The guidelines presented in this chapter have proven to be effective for improving the quality of designs and ultimately the quality of the end product.



1. John D. McGregor, The Fifty Foot Look at Analysis and Design Models, Journal of Object-oriented Programming, July/August 1998.

2. John D. McGregor, If the Devil is in the Details Then What is in the Plan?, Journal of Object-oriented Programming, January 1999.