Unified Modeling Language is about communication. But in order for communication to work, it must be useful. How do you make sure that you don't sweat over a set of UML diagrams only to discover that no one else can understand them? Fortunately, there are guidelines, discussed in this article, to help prevent this catastrophe. This article is excerpted from chapter three of the book UML Applied: A .NET Perspective, written by Martin L. Shoemaker (Apress, 2004; ISBN: 1590590872).
One of my favorite television programs is The Learning Channel series Junkyard Wars (also known as Scrapheap Challenge on the BBC). This reality program has a great geeky premise: place two teams of engineers in a junkyard with an assignment to build something, such as a catapult or a submarine; give them a time limit; and when the time is up, pit the contraptions against each other in a contest sure to test them to the limit. In the semifinals for the 2000 season, the NERDS—a team of American programmers—built the winning steam-powered car (proving that yes, programmers can do hardware, if we want to). And along the way, they propounded The MTB Rule:
Design checks (aka MTB: Minimum Two Brains)—When you are about to build some part of your machine and it’s not totally trivial, grab some (any) other team member and explain it to them. If they agree that’s a good way to do it, do it. If they find a problem with your way, come up with a solution. If it isn’t clear, call a Team Design Review and spend five minutes getting it right.2
Communication—you know, that thing that UML is about—requires a Minimum Two Brains: one that proposes the idea, and one that responds to it. And then the magic begins, we hope: the two brains change roles, back and forth over one idea after another, tumbling ideas against each other like rocks in a tumbler, polishing them to a bright shiny finish.
Can you use UML with only one brain? Certainly, just as you can write a novel and never let anyone read it: you can enjoy the craft of writing, and you can practice your skill with words, and you can even use the unpublished novel as a springboard for other projects. The time isn’t wasted; but you’re only getting a tiny fraction of the benefit you can get when you share your ideas with others. For UML design is an activity very much like writing; and Stephen King tells us:
What Writing Is. Telepathy, of course. It’s amusing when you stop to think about it—for years people have argued about whether or not such a thing exists, folks like J. B. Rhine have busted their brains trying to create a valid testing process to isolate it, and all the time it’s been right there, lying out in the open like Mr. Poe’s Purloined Letter.3
With a clear UML design, you can pull an idea from your brain and insert it into another brain. Then you can view that idea from a new perspective, that of a brain that didn’t conceive the idea originally and thus perceives it from different angles and a different background. This becomes an exercise in statistical coverage: if one defect in ten will slip past a single brain, then one in a hundred will slip past two brains, and one in a thousand will slip past three. There is some number of brains for which the marginal return is less than the overhead cost of adding another brain into the mix; but although I can’t tell you what that number is— it varies based on the project, the team, and the organization—I can assure you that the number is always greater than one. We all can benefit from an editor or a reviewer.
This review process is often not pretty: one of the brains is very emotionally attached to an idea that springs from deep within that brain; and the other brain is skeptical, having seen far too many good ideas that crumbled to dust in the rock tumbler. These two perspectives will clash, and both brains may be bruised in the impact. Thick-skinned brains are essential; but the impact can be cushioned quite a bit by clear communication. And that is what we hope to see in our UML diagrams.
The 7 ± 2 Rule
There’s a very simple reason why UML is primarily a diagramming language: a picture is worth 2 kilobytes, after all. That’s roughly a thousand words. Oh, all right, if you think like a mainframe programmer, call it 4 kilobytes. (God, I hate having to explain a joke.) Cognitive scientists tell us that the brain processes pictures in a different way and in different paths from those involved in processing text and formulae (i.e., code). So one advantage of diagrams as a design tool is simply that they cause you to think about the problem differently. But there’s another, simpler reason why diagrams are useful: the brain processes text one word or phrase or line at a time; but it processes a picture all at once. You can see, as they say, the Big Picture.
But there’s a limit to the effectiveness of pictures in this regard: the brain can keep only so much of a picture all in memory at one time. Cognitive scientists (who have a whole lot to teach about problem solving and how we approach it) also tell us that the average human brain can keep in its short-term memory only seven things, plus or minus two.4 This limit constrains the level of useful detail in a diagram. Beyond that range, details begin to blur; and the brain can only comprehend a part of the picture, focusing on one aspect to the exclusion of others, or focusing on no aspects and simply grokking the entirety with no sense of detail.5 The image becomes the Too Big Picture.
Does that mean I never draw a UML diagram with 10 elements, or 15, or 20? Mea culpa: I understand all too well that sometimes proper communication seems to demand more elements. (Note how I said seems: when I find my diagram fails to communicate, I can most often find the cause simply by counting the elements in the diagram. To my chagrin, the answer will be much more than 7 ± 2.) Clutter is always a danger in a complex system design. Remember: “comprehensive” does not mean “comprehensible.”
There are two common situations in which it makes sense to break
The 7 ± 2 Rule:
1. When you have a large group of related elements—species of animals, for example—and you want to show their relations to each other and to other elements—biological classifications, perhaps. Although it makes sense to draw this sort of diagram, the result can still be a confusing diagram. You can improve the legibility of such a diagram by grouping the related elements physically on the page. The brain will then group them together mentally as well, and will treat the group as a single element related to the nongrouped elements (thus reducing the complexity at the expense of detail). When the brain wants to understand detail within the group, it zooms in on the detail at the expense of the larger relations. For an example of this technique in action, study Michelangelo’s painting on the Sistine Chapel ceiling: it tells a complex story in many panels that collectively make up the familiar story of Genesis (and related motifs); but within each panel is rich detail worthy of a masterpiece by itself. You can see the story, or the detail; but it’s very difficult to see both at once.
2. When you want to show the entire sweep of a system, the whole that is larger than its parts. This sort of diagram—what I like to call “The Everything Diagram”—is popular with managers who want to know that there’s a place for everything and everything is in its place. The sense of security that gives them is false, I think: the diagram is too complex for anyone to ever really know that it’s accurate or to comprehend the roles of individual elements. It becomes a single image made up of many tiny elements, rather than a useful description of the elements themselves. When you look at Van Gogh’s Starry Night, you see a cypress tree and a little village set against a turbulent night sky, not the individual brush strokes that make up the shapes of the tree and the village and the sky. If you were to concentrate on the brush strokes instead, you would find that they look like nothing whatsoever; but the impression formed by all these nothings is recognizably Starry Night. The value of an Everything Diagram is more navigational than communicative: you can use it to trace a path through related elements involved in a scenario. But once you have traced the path, you will comprehend the path more fully if you create another diagram consisting solely of those related elements.
What counts as an element for purposes of The 7 ± 2 Rule? Primarily, the icons: actors and use cases in Use Case Diagrams, objects and activities and swimlanes in Activity Diagrams, objects and actors in Sequence or Collaboration diagrams, interfaces and components in Component Diagrams, classes and interfaces in Class Diagrams, states in Statechart Diagrams, nodes and devices in Deployment Diagrams, and notes and packages in any diagram. Other features in a diagram are closely associated with a given icon or depict the relationships between icons, and thus can be understood within the context described by the icons themselves.
Learn from the Masters
It’s no accident that I chose famous paintings as metaphors in the preceding examples. The great artists have spent generations studying techniques for communicating visually: discovering rules, breaking rules, and testing the results to “see” what they learned about the rules. I’m never ashamed to adopt the lessons learned by others, so that I can focus on the new lessons I must learn. If you want to use UML for better visual communication, it couldn’t hurt to spend a day in an art museum.