Keeping Your Sanity with UML

by Gary K. Evans

The Unified Modeling Language (UML) is a notation for expressing object-oriented concepts, and the interactions of system components. With the release of UML version 2.0 in July 2005, this de facto standard for modeling object-oriented concepts achieved a new level of complexity. When confronted with an industry standard like UML 2, it is too easy to presume that a software project should use all of the standard in order to be in correct compliance. Fortunately, this is not a requirement for success with UML. Not every project needs even most of UML, and most projects require more than UML alone offers. The main criterion for adding UML diagramming to your project artifacts is that a given diagram will move your project forward.

While UML 2 offers 13 diagrams for modeling a software system, many practitioners of UML modeling use only a "sane subset" of UML on most projects. This core set consists of the:

• Class diagram
• Sequence diagram
• State Machine diagram
• Activity diagram, and
• Use Case diagram

Class Diagram

The UML class diagram is the centerpiece of most modeling efforts. The class diagram describes the major entities (i.e. classes) in the system, and the static relationships among those entities.

The class diagram is part of the core subset of UML because the structural perspective it offers is tied to all the other core diagrams. Customers and end-users can appreciate the class diagram and learn how to read one in 30 minutes. It can be easily tailored to convey either an analysis perspective, or a design perspective. A simple analysis class diagram allows your end-users to validate your understanding of their business domain, so you and they can achieve consensus on the project goals.

Developers benefit directly from constructing design-level class diagrams. Modeling tools can generate object-oriented language code from the class diagram, and the code they generate is the "scaffolding" code to support the classes, relationships and multiplicities shown on the class diagram. Every project must produce one or more class diagrams, but should not ignore the benefits of the core UML behavioral diagrams which I discuss next.

Sequence Diagram

The sequence diagram, or SQD (pronounced "squid"), describes the interactions over time among two or more objects. In my consulting and modeling experience the SQDs are the single most important diagrams you will do on a project. The class diagram is essential, but the SQDs let you visually confirm that your classes are defined properly to carry-out the work of your system as specified in your use cases or user stories.

Business analysts construct sequence diagrams to convey to developers how the major entities in the business should interact with each other in various business scenarios. Developers can produce sequence diagrams to thoroughly explore the implementation classes they need, and how these classes invoke each others’ methods to produce correct system behavior.

State Machine Diagram

The state machine diagram describes the set of states defined for a single class, the events which trigger transitions from one state to another, and the major activities which are performed in each state. The notation was developed in the 1980's, and I have always been puzzled that state diagramming is so seldom done in our industry.

The state machine diagram benefits business analysts because it allows them to unambiguously specify events that represent business rules and constraints, and how system behavior should be partitioned across the various states in the class's state space. Developers benefit because the state machine allows for discovery of operations (methods) in the class being modeled. In particular, state machines are a rich source of discovering private methods on the class being modeled.

Activity Diagram

An activity diagram is like a flowchart - only on steroids. Not only can an activity diagram model sequential processes, it is especially adept at showing concurrent (parallel) behavior among business entities or classes in your system. This ability to illustrate concurrency is a singular advantage of the activity diagram.

Analysts familiar with Business Process Modeling Notation (BPMN) should readily appreciate this notation, as well as the partitions that let us allocate activities to specific business units or domains. Activity diagrams are very useful for modeling interactions in business workflows involving multiple business domains acting in parallel. Developers benefit from activity diagrams as a tool to represent interacting processes or threads running concurrently.

Use Case Diagram

The use case diagram describes the major services provided by the system being modeled, and the external entities (i.e. actors) that interact with the system. I have listed this diagram last because it has rather limited business value on most projects, but it does offer a concise means of illustrating the major services provided by a system, and the groups of users and collaborators interacting with that system.

The use case diagram benefits all project stakeholders by illustrating the major services in the system, as well as offering a simple specification of user categories, as well as external systems and components that will collaborate to support the goals of your system.

Conclusion

These are the core UML diagrams you should consider using on your projects. The class diagram, sequence diagram and the state machine diagram are the "inner core", if you will. I develop these on every project. The use case diagram provides benefit for organizing our thinking about users, services and external components, but is replaced rather quickly by the actual use case descriptions. The activity diagram is always ready to be used when we need to describe a specific algorithm, or when concurrency is part of our system design. When we do not have concurrency we may not need the activity diagram at all.

UML is all about communication, and these five diagrams are a powerful toolkit for communicating your system's goals and design to your project constituencies.

Visit our website for a more detailed version of the article above, including examples of all five core diagrams.

    Gary K. Evans

Jolt Award Nominations are Open

The 19th annual Jolt Awards are underway. Do you have a software product that you just cannot live without (one of mine is Visual Slickedit), or that you think has seriously improved the way you develop or manage software? Then encourage the vendor to nominate that product for the JOLTs at the Jolt Awards site. All 13 product categories are listed there.

I have had the privilege of being a Jolt Judge for 10 years. I moderate the Design and Modeling Tools category, and judge in that category as well as Development Environments, and Mobile and Web Development. All judges volunteer their time, and it is an exhausting but exhilirating experience to see and use the latest and best software products. Please pass the word to your colleagues and encourage them to rally their "must-have" tools. Previous award winners are also posted on the Jolt site. Nominations close November 12, 2008.