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).
We saw The Model Rule in Chapter 1; but it bears repeating. To use UML effectively, you should never be simply drawing pretty pictures; you should always be editing an underlying model, using the pretty pictures as your user interface. Thus, the model should contain more information than is displayed in any one diagram, and information in one diagram shouldn’t explicitly contradict information in another diagram. Information that is found in one diagram but not in another shouldn’t be considered a contradiction. Rather, this simply indicates that the former diagram displays more detail than the latter. Details may be omitted from any given diagram to make it more comprehensible.
But how do you keep these diagrams consistent with each other? How do you maintain the underlying model? This is where a good modeling tool proves its worth: a good modeling tool will maintain the model as you create and edit your diagrams.
If you aren’t using some sort of modeling tool, this very mechanical burden will fall on you, rather than on the machine. That’s a poor division of labor: brains should do brain work and machines should do mechanical work. If you do the mechanical work, you’ll do it imprecisely and inefficiently, and you’ll have no time for brain work. I urge you to investigate and use one of the many UML tools available. A list of UML tools can be found in Appendix B.
“Legible” Does Not Mean “Pretty”
The point of UML is—do I even need to say it?—communication. But there are different kinds of communication, even when the medium is the same. For example, speech is a very common communication medium; but there’s a very wide range of speech styles that all manage to communicate. The stops and pauses and half-finished sentences and even grunts of a casual phone conversation between old friends are very different from the formal, scripted, ritualized sentences of a traditional marriage ceremony. Yet each is a successful style of communication.
So which should you prefer? Well, just imagine holding every conversation in your day with the same degree of formality and structure of a marriage rite. It would sound like parody:
“I, Martin, ask thee, Sandra, if thou wouldst enjoy a noon repast with me?”
“I, Sandra, ask thee, Martin, if thou may tarry a brief moment, and that thou might help me to escort our canines into yon field? Else, I fear, they shall do in our abode that which canines should do in fields.”
“Yea, verily, shall I assist you in this, as in all endeavors. I shall fetch the Dane.”
Compare this with an actual conversation:
“Hey, Sandy, ready for lunch?”
“Just a minute. Help me take the dogs out first.”
“Glad to! I’ll grab Betsy.”
The casual conversation ain’t pretty. It ain’t even grammatical, in every particular. And it leaves a lot unsaid, requiring the participants to fill in a lot of blanks. But it’s real. And it’s also economical (20 words versus 72), and it gets the job done. Plus, it’s a lot easier to create.
We create casual conversations on the fly, nearly as fast as our thoughts can flow. We create formal conversations by careful planning, thought, rehearsal, revision, and review. That slows down the fundamental process of thinking because the thinking is concentrated too much on form and not enough on substance. Now we can’t take this too far: we can’t casually invent words and usage any time we wish, without also slowing down communication. We do so only when it serves a greater purpose, our ultimate purpose: communication.
That’s the approach you should take to communicating with UML: legible over pretty, and standard over creative. Put in as much effort and as much customization as needed to get your point across; put in no effort on unnecessary prettification, and customize only when the standard notation fails to communicate efficiently. If you’re drawing diagrams by hand, make the lines and shapes as straight and regular as you can, but don’t break out the ruler and compass and protractor. (Fine-ruled graph paper helps a lot, though.) If you’re drawing diagrams with a UML tool, stick to the easier features of the tool, and use more esoteric features only when necessary.
Maybe Even Ugly?
In case you haven’t noticed by now, I see the primary value of UML in its role as a communication tool. But in Agile Modeling, Scott Ambler describes another value of UML.1 He talks of “modeling to communicate” versus “modeling to understand.” The latter is another perspective on The Outline Effect that I described in Chapter 1: a way of understanding a problem by building a model of the problem, or even of understanding existing code by building a model of it. This is certainly a valuable use for UML; but when you’re modeling to understand, like this, you may go even further in the direction of legible versus pretty. In fact, you may very well produce some pretty ugly diagrams.
Don’t let this worry you, and don’t let it slow you down. When you’re trying to understand something, “cleaning up” diagrams will only distract you. If you can read it, it’s good enough. Move on. Keep the momentum going. Making sense of a new problem domain is hard work. Making sense of existing code is even harder. (Robert L. Glass, author of Facts and Fallacies of Software Engineering, argues that it’s one of the most important and least taught skills a programmer can have.) Comprehension is hard, and neatness isn’t necessary for it. You can always clean up later, when your brain goes into idle and you’re just going through the motions. I’ve spent many hours rearranging diagrams to make them more legible, while simultaneously listening to the TV or even taking part in a conversation. I don’t want to imply that legibility is easy; but it doesn’t take the same sort of intense concentration that’s required for comprehension.
There’s a place for pretty, just as there’s a place for formal, ritualized speech. In fact, the places are the same: any occasion of ceremony, of transition. You can and should apply extra polish to diagrams that are to be presented in large, ceremonial settings (sign-off meetings, executive presentations, etc.), because it demonstrates attention to detail that will give participants confidence. No, strike that, they won’t notice the detail; rather, if you don’t apply the polish, they will notice the unpolished details, and their confidence will be shaken.
And there’s one other place where a little effort on pretty goes a long way: when you have to prepare diagrams that others will read when you won’t personally be there to guide them through the rough spots—like, say, when you’re writing a book on UML. You don’t want to see the diagrams in this book the way they looked when I was just getting my thoughts together. I put in a lot of effort to clean them up to help you understand them as best you could. But in your day-to-day work, you should do exactly what I do in my day-to-day work: I get the diagram to the point where I think it makes sense; and then I hand it to someone else and ask if it actually does. And that leads us to . . .