Pragmatic Guidelines: Diagrams That Work

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).

IN THE LAST CHAPTER, we spent a long time working through the process of Five-Step UML, and looking at all of the new UML notation which that entailed. But in this chapter, we’re going to take a quick break from learning all the formal rules and all the step-by-step instructions on how to use UML as part of a modeling process. Instead, I’m going to present a set of pragmatic guidelines that will help you stay on the right track during your development work.

By this point, you may already be tired of hearing me say that UML is about communication. But that’s easy to say, and much harder to do. Listen to any political speech, and you can hear lots of words with no real meaning communicated. Read the telephone book from cover to cover, and you’ll find lots of factually accurate information that’s too voluminous and too complex to be useful.

The same sorts of things can happen with UML diagrams: you can make a set of diagrams that seem to say something, but that actually fail to communicate. You can pour time and sweat into getting the lines just right and all of the right icons in the right places, only to find that no one else can understand what you drew. You are, quite literally, back to the drawing board.

This frustrating event is going to happen to you. Nothing can prevent it, and it’s part of the normal, healthy design process: the missteps are merely steps to a better design. The only designers who never design anything poorly are those who never design anything. But there are some common mistakes that you’ll see in your own work and in that of others.

The following guidelines are my attempt to warn you away from some of these mistakes. And despite some of the names, they are guidelines, not rules. You can break them, and still communicate. Sometimes you must break them in order to communicate. But when you find that one of your diagrams is failing as a communication tool, check these guidelines: chances are, the bridge for your communication gap is here somewhere.

Do What Works

The number one guideline is that simple: Do What Works. Not what’s right. Not what’s “supposed to be done.” Not even what I tell you to do. Just what works. At the end of the day, if you don’t communicate, if you don’t solve a problem, you haven’t succeeded. Don’t let me or anyone else sell you on “the one true way to produce software.” We may be very bright (or think we are), and we may have really good reasons for what we’re saying; but maybe those reasons depend on factors that don’t apply in your situation.

And this is (unfortunately) a slippery rule: “what works” changes for different purposes, different problems, different audiences, and a range of other variables. I’ll look at that in a bit more detail in the next three sections.

Purpose

If your purpose is to document an existing system, you’ll probably start with Class and Component Diagrams that reflect its structure, and then add Interaction Diagrams to show how that structure works, and then add Use Case Diagrams to show the externally visible behavior embodied by those interactions. Then, as you extend and maintain the system, you’ll update and add to those diagrams. But if your purpose is to design a new system, on the other hand, you’ll start with Use Case Diagrams to depict requirements in context, and then work in. If your purpose is to understand a strange bug, you might start with Interaction Diagrams. Your purpose will also determine the level of detail you apply: if you’re just trying to understand some existing code, you might apply much less detail than you would in designing new code.

Problem

For a small problem, too much modeling can bury you in paperwork, and you’ll suffocate. For a large problem, not enough modeling can mean that your vision isn’t abstract enough to encompass the system at varying levels of detail. For a familiar problem, a single stereotype icon on a diagram can convey pages of meaning to the team; and too much detail really doesn’t communicate anything new, because “We’ve seen all this before.” For a new problem, you’ll need much more detail, because people need lots of help learning the new domain.

Audience

For your fellow developers and designers, you’ll add lots of detail. These people are basically pre-reviewing your code by reviewing your design; but if you don’t include enough detail to demonstrate that you know what you’re doing, trust them to call you on that. (And if you can’t trust them for that, what good are they?) But for business analysts, customers, and other nontechnical stakeholders, this detail is just clutter: they don’t know what it means, they don’t want to know what it means, and they’ll get it wrong if they try to know what it means. For them, you draw less-detailed diagrams, but perhaps try to fit a broader scope into each diagram.

A .NET Perspective

In particular, what works well for me in .NET modeling is reverse engineering. My UML tool of choice, Rational XDE, is one of many that will generate the elements of a model from your source code. So often, after I have gathered requirements and started on a shell of architectural design, I’ll use the powerful tools in Visual Studio .NET to generate the basic components of my architecture; and then I’ll reverse engineer those components into my models and incorporate the reverse-engineered elements into my UML diagrams and designs. So I’m not a modeling purist: sometimes I start with a model and lead to code, and sometimes I start with code and work towards a model. But either way, my real approach is circular: code leads to models leads to code leads to models leads to . . .

Using a Tool

So though I describe some useful steps for applying UML, my real technique is to do whichever step makes most sense next. That’s one advantage of a good modeling tool like Rational XDE: no matter what I discover or envision, there’s a place for it in the model, and I can put it there quickly, explore it as much as I need to right now, and go back to what I was doing when the topic came up, with only minimal interruption. Then later I can go back through the model and find all these proto-ideas and work on fleshing them out. The model evolves very naturally this way. And that leads us to . . . 

{mospagebreak title=The Model Rule}

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 . . .

{mospagebreak title=The MTB Rule}

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.


{mospagebreak title=The Résumé Rule}

There’s another problem with the Everything Diagram: either it’s too darn big, or the font is too darn tiny. You’ll be tempted to zoom out to fit everything, and then play games with the font to make it legible. But there are limits to that approach: when the font size is 1 point, it really doesn’t matter what the font face is; and if you enlarge the font disproportionately to the icons, the labels can obscure the icons. No one can review a diagram they can’t read. Amount of information communicated: zero.

So you’ll err in the other direction: larger diagrams at a scale you can read. Beware! That way, madness lies. You might split the diagram across many pages. Then you’ll ask me to review it. Unlike you, I don’t automatically recognize how the pages fit together. (Let’s be honest: you may not, either.) So I take it home to review. First, I have to clear off the kitchen counter so I have space to lay it all out. Then I have to throw the cat off the nice clear spot she’s just discovered. Then I have to try to lay out the pages. Then I have to throw the cat off again, because if there’s one thing she likes more than a clear counter, it’s whatever piece of paper is most important to me at the moment. Then I have to quiet the dog, who has decided that I need help disciplining the cat. Then I have to pick up the sheets that the cat knocked off the counter in her rush to escape the dog. Then I have to figure out if those marks are cat prints, dog slobber, or UML . . .


Plotter Horror

Or you’ll make the mistake I did: learning the arcane art of using the company plotter. Now I hope that plotters are better supported today than they were then; but in 1997, it took me and my boss all day to download the correct drivers and install them on my machine. (We installed a lot of incorrect ones along the way.) Now, truth to tell, I’m a night owl. We had that driver working at 5 p.m., just when my energies were really flowing; so the wasted day didn’t bother me. I proudly printed my first UML diagram to the plotter. Then, because of the physical layout of the company offices, I had to go up a flight of stairs, down a hill, around a corner, down another hill, around another corner, down another hill, across a busy street, around yet another corner, down yet another hill, through a security door, through a building I didn’t know, into the plotter room . . . only to discover that the diagram had printed incorrectly! So reverse the process (all uphill this way, of course), and repeat. By 11:00 p.m. (what a waste of prime programming time!), I finally had copies of all six diagrams I needed, one copy for each team member. I rolled them up, put them in tubes, and capped the ends. Then I carried all these tubes back up the hill, and put one in each team member’s cubicle, along with a handwritten note: “Hi! Martin here! These are the diagrams I promised you for review. I’d like to hold a review meeting Tuesday at 10:00 a.m. I look forward to your feedback. Thanks!” And then, Tuesday at 9:55 a.m., I heard pop! Pop-pop! Pop-pop-pop! All over cubeville, tubes were being uncapped for the very first time. Needless to say, that review was not very productive.

Your logistics may not be as bad as mine were. The plotter may be right next to your desk. But the result will be the same: your reviewers will glance at your work, compliment you on how much effort went into it, and never once review your design. Amount of information communicated: again, zero.


The best solution is the same rule the guidance counselors taught us all for résumés: one page. If a diagram can’t fit legibly on a single 8½×11″ page, no one will review it. Although it’s true that such a page can get buried in an in-box, it also can easily be carried home in a briefcase, read on the airplane, and photocopied for more reviewers. The standard page size is overwhelmingly more convenient than is a great big plotter sheet or a diagram that must be laid out along an entire kitchen counter.

What if your diagram won’t fit legibly on a single 8½×11″ page? Then, first of all, it’s likely that you have broken The 7 ± 2 Rule, but more significantly, you probably have too much detail at too many levels of scope. You can usually group many of the elements of such a diagram into fewer, larger elements, each with its own attached diagram on another page. Although it may seem to you like more work to add these additional elements and diagrams, that is from your perspective as the designer and originator of the idea. From an outside perspective, you’ll end up with a more comprehensible set of diagrams that convey your intent.


Sorry for My Cultural Centrism

Yes, I realize that in other parts of the world, 8½×11″ is not the standard page size. Don’t take me too literally here. Use whatever is the standard page size for your locale. (Perhaps in those cultures, this should be called The Curriculum Vitae Rule.) But be hesitant of nonstandard sizes, even that of the infamous “yellow legal pad,” because they tend either to get lost in piles of larger paper, or they stick out of piles of smaller paper and get smudged, snagged, and ripped. Take a look at your last pointless memo from human resources, and use that size paper.


With both The 7 ± 2 Rule and The Résumé Rule, remember that you as the designer are not the best judge of what is comprehensible. First, as I discussed in Chapter 2, you’re weird: as a software developer, you’re better than the average reviewer when it comes to managing abstractions. So when you’re sharing your model with nondevelopers, they may be at a disadvantage. But even other developers won’t read your diagrams as readily as you will. When you read your diagram, you’re reading the real picture that’s already in your brain; but when reviewers read your diagram, they are reading the diagram and trying to understand what’s in your brain. Those reviewers need a lot more help than you do. And that leads us to . . .

“You Just Don’t Get It!” Is Never an Excuse

As the designer and originator of the idea, it’s your responsibility to communicate it, and no one else’s. As long as the reviewer makes a reasonable effort to understand the idea, it’s up to you to make sure that effort pays off. The only measure of successful communication of an idea—in a slippery, circular sense— is when the idea is communicated back with no errors (and preferably in a different form). Until the reviewer understands the idea, you haven’t communicated. Keep trying.

But how do you keep trying? Try another approach:

  • Add more detail to your diagram, to make a better picture of what you need.

  • Remove detail as a way to reduce clutter. Every diagram need not display every detail. Remember The Model Rule: completeness lies in the model, not in any single diagram.

  • Remove the detail—and maybe even some of the major elements— and place them in another diagram.

  • Redraw the diagram. If you can’t get your point across, maybe a fresh start will inspire you to a better way of presenting the information.

  • Ask reviewers to create a diagram of what they do understand. Perhaps when you see their interpretation, you’ll discover where the miscommunication lies, and you can correct it.

Don’t I ever get frustrated? Don’t I ever run into people—real, competent developers—who just don’t get it, just can’t see how superior and brilliant my idea is? Sometimes I think I do; and then I recall the words of Jim McCarthy:

The clearest sign that people are thinking is that they listen to other people’s ideas and critical feedback. They quiet their initially competitive responses to a possibly superior line of thought. They demand of themselves the intellectual rigor it takes to fairly and properly evaluate the new, potentially valuable information. They can filter out the ego-driven aspects of the communication they’ve just received because they can bring an understanding of human nature to a distillation of the true spirit of the message from the raw communication of it.6

And then I apply those words, not to the other programmer, but to myself. If I can’t explain my point to my fellow developers, at least I can listen to their point. It matters not in which brain communication begins; it matters only that it begins.

{mospagebreak title=Every Picture Tells a Story}

This is a corollary of the previous guideline and of The Model Rule: you draw those diagrams that answer questions or explain points. Every diagram should have a purpose that you want it to communicate to your audience. For each diagram, you should be able to convert the diagram to a PowerPoint slide, project the slide on a screen, and explain the story of that slide within the recommended 2 minutes per slide. The audience should be able to grasp the point of the story with minimal reference to other material. Although some amount of knowledge of the model behind the diagram will be necessary, each diagram should be complete enough to tell its story on its own. Add notes where necessary to fill in gaps in the explanation.

Conversely, examine the detail on each diagram. If a particular detail doesn’t add to the story, consider removing it; and if some detail detracts from the story, definitely hide it within the current diagram.

Some stories are too large to tell in 2 minutes with one diagram. This is another example of how multiple diagrams at different levels of scope can make your communication more clear. Tell the broad outline of the story in one diagram; then bring the scope down to tell individual stories where they make the design more clear.

The Highway Map Rule

As the number of diagrams and models grows, some people will worry: “How do we keep this up to date as the code evolves?” Those in the Extreme Programming/ Agile Development worlds will answer: “You can’t, so don’t bother trying. Once you’ve got the code, throw away the model.” Their focus is entirely on functioning code, and maintaining the model past the point of coding is considered extraneous effort. And worse, because they’re not maintaining the model consistently with the code, the model will eventually be misleading: the model will lead you to believe the code works one way, when it really works another. In their view, the code is the only true design; and once a model helps you produce code, the model is “wrong” after that, so throw it out.

And then, of course, there are those with less discipline: those who use this mismatch between model and code as a justification for never modeling at all.

Well, I understand these concerns (except for those who never model), but I think they’re wrong-headed. For an example of why, I point to the highway map in the glove compartment of my car. This is a map of Michigan (the state where I live), which I use to navigate to any part of the state that I don’t already know how to find. It’s also a useful way to teach someone basic Michigan geography. Without the map, I could set you down outside my front door, and let you start walking. In a few days, you would probably know a lot about the square mile closest to my house; but with the map, you could learn the major cities and highways in Michigan in less than an hour (and you wouldn’t have to walk anywhere). So the highway map is pretty useful, except for a couple of problems:

  • The map lacks detail. It covers over 160,000 square miles in around 1,100 square inches, a scale of nearly 1,000,000:1. That means that my entire local village of Hopkins—about half a square mile in area—should take up a square 0.04 inches on a side, and that’s about the size of the dot that represents Hopkins on the map. But there’s just no way to legibly draw the 22 streets of Hopkins within that dot. All you see of Hopkins is a dot. This is true for most Michigan cities: they appear as dots or larger geographic areas, but with only major streets drawn in. Only a few of the largest cities are reproduced at a larger scale so that you can see the streets in more detail. (In this way, the map is consistent with my advice to make your model out of multiple diagrams.) So there are many things in the real world that don’t appear in the map.

  • The map doesn’t show the inevitable highway construction that takes place on practically every Michigan highway, all summer long. And the map is static, not dynamic, so it also doesn’t show the inevitable traffic jams that occur on certain streets at certain times of day.

The map is wrong, in other words. So if I plan a route from my house to the monthly Ann Arbor Computer Society meeting, it’s very likely that the map will mislead me. For instance, on one recent trip, the map didn’t show the traffic jam that occurred in Jackson during rush hour; and the map didn’t show the road construction between Ann Arbor and Jackson that exacerbated the traffic jam; and the map certainly didn’t show the traffic accident (caused by the traffic jam, perhaps) that brought traffic to a complete standstill; and when I got frustrated with the progress and got off the highway onto local Jackson roads, the map didn’t show enough detail to guide me, so I had to explore by myself.

So I should throw the map away, right? The only real design is the streets themselves, and the pattern of traffic on those streets, right? Yeah, the map could be updated to show all those details; but that would take too long to be worth the bother, right?

Of course not! We don’t throw away models just because they’re inaccurate or incomplete. The problem of keeping models and implementation up to date is not unique to software: building architects have to constantly revise their architectural blueprints to reflect the building as built; car designers have to update designs to reflect last-minute design changes; and map makers must occasionally print new maps to reflect new roads. And in fact, it’s far easier for us to maintain software models than for others to maintain their models: automated tools can reverse engineer most of the structural changes, leaving it to us to model the behavioral changes based on those structural changes. (Building architects can only wish for that kind of power.)

As George Box once said, “All models are wrong; some models are useful.” Even though our models are wrong, they’re useful:

  • The requirements model documents the intent of the analysts and the users.

  • The architecture model documents the modular breakdown of the system, and thus probably the breakdown of teams and assignments and responsibilities as well.

  • The design models are broad-scale maps to what’s in the code. To say, “The code is the design,” is simply impractical: it doesn’t scale well. Any given diagram may reflect hundreds or even thousands of lines of code. If you try to comprehend that code a line at a time, you might never be able to understand the system; but if you try to comprehend a model first and then dig into the code for more specifics, your understanding will grow much more quickly.

So if you don’t throw out the models (except, perhaps, for temporary models: proof-of-concept sketches that you throw together just as you’re playing with ideas), when do you maintain them? It’s not possible to be constantly changing your model, updating every single time you make a change to your code. Instead, you should consider one or more of the following approaches:

Frequently

  Every time you start a new phase of development—a new 
  release, a new iteration, a new set of requirements—start by
  modeling what is new and what has changed.

When you inherit code, and nobody ever bothered to 
   create a design for it in the first place

          A powerful technique for learning existing code is to reverse
          engineer the existing structure with an automated tool, and
          then to reverse engineer the behavior of that code by reading
          the code and reading the structure. As you learn what the
          code does, capture that understanding as Use Case, Activity,
          and Sequence Diagrams. This is one example of The Outline
             Effect
at work (see Chapter 1).

When you see a problem

  In Refactoring, Fowler7 describes this approach when it comes 
  to code: when you see an opportunity to improve code, you
  make the change immediately (and then thoroughly test to
  ensure that you didn’t break anything in the process).
  Essentially, you “polish” the code wherever you see that it’s
  tarnished. Similarly, if you see that the model is incorrect or
  incomplete in an area where you’re working, don’t throw the
  model out, and don’t ignore the problem. Fix the problem now,
  when you see it. This way, the model naturally improves
  precisely in those areas where the most work is being done.
  This is another way to leverage The Outline Effect: by fixing
  the model, you have to think about the existing code and your
  new code more thoroughly, and will be thus more likely to
  make correct changes in both the model and the code.

When you can’t see a problem

  If you’re chasing down a bug and you can’t find it in the 
  model or in the code, make a new model, based on the code. 
  That will be an “as built” model. Then compare the “as built” 
  model to the “as designed” model. The contrast will give you 
  one more way of looking for the bug. Then, when you find it, 
  fix the “as built” model, fix the bug, and replace the “as 
  designed” model with the “as built” model.

When it hurts

  When you find that the model is consistently wrong and  
  consistently misleading you in understanding the code, take
  time out to bring it up to date.

Some developers advocate an approach whereby they don’t bother updating the model, as long as it still conveys the correct intent of the code, even if the two have become inconsistent in places. But if the model and code have diverged to such an extent that the code is unrecognizable with respect to the model, then the team should have a meeting, to figure out whether the model is wrong or the programmer just decided to do his own thing. The value of models in this kind of situation is in their ability to capture intent, more than implementation. As ever, follow rule number one, and Do What Works.

So in summary, The Highway Map Rule is this: throw away temporary models; keep permanent, official models; update the official models as you get the chance; and don’t get overly concerned when the official model and the code aren’t quite in step.

{mospagebreak title=Define Your Own UML with Stereotypes}

We have seen stereotypes a lot in our models so far. Now it’s time to explore them a little more completely.

An important thing to realize is that the U in UML means Unified, not Universal (a common misconception). The UML authors recognized early on that a “universal” notation is an impossible dream: any attempt to make a universal notation was doomed to fall short, but would end up with a large, bloated notation that no one could use.8

So instead of striving for universal, the UML authors settled on extensible; and the primary extensibility mechanism they defined is stereotypes. A stereotype is a label applied to an existing element of UML notation that carries some extra meaning beyond the UML element itself. When you define a stereotype, you may also define a custom icon for that stereotype that replaces the standard icon for the base element. Then, when the stereotyped element appears in a diagram, you may show the stereotype either by using the custom icon (if any) or by listing the stereotype name in guillemets (« ») or double angle brackets.

In essence, stereotypes allow you to define your own “dialect” of UML: particular recurring modeling concepts that you want to express with a shorthand visual or text notation.

To define a new stereotype, first . . . well, first go read the Three Amigos’ The Unified Modeling Language User Guide and The Unified Modeling Language Reference Manual. Although not universal, the UML is huge. It contains many obscure notations for special needs. Then go read their Unified Software Development Process for some useful stereotypes that they recommend for business and process modeling. Review other sources and see if the stereotype you need already exists. Before you go reinventing the wheel, see if someone will give you one, one that other people may already recognize.

But after you’re sure that you need a new stereotype, find the UML element that comes closest to your new concept. Often this will be a class or actor; but it might be a use case, a component, or any other element of a UML model. Then define a stereotype named for the new concept. Document the new stereotype: what it means, why you need it, why it occurs often enough that a simple note won’t suffice, and why an existing UML element won’t suffice.

After that, you can apply your stereotype throughout your model. When someone asks what the stereotype means, point them to the documentation, and then answer their questions. The purpose of the stereotype is to make a simple way to communicate complex recurring concepts; but before you can use it, you have to make sure people understand the complex concepts.

Don’t get carried away with custom stereotypes. You need them occasionally, and they can really increase communication within your team; but there’s a risk that they will decrease communication with newcomers who do not yet know the stereotypes. For instance, I find that casual readers of Use Case Diagrams can get confused by actors, because they are depicted as stick figures even when they don’t represent people. Sometimes a reader will even ask, “Who is this person called ‘Mainframe’?” So I usually define the following custom stereotypes and icons in my designs:

    
                                                       

These should be familiar concepts that are obvious to anyone who reads the diagrams. If the intent of the diagram is communicated more clearly by using custom icons, use them! But this customization may be carried too far. For instance, this icon may connote a great deal of information to someone who knows the Kennel Management System, but not as much to other readers.


                                                         

Pet Worker is anyone who works with pets directly, as opposed to someone who works with the system but not with pets. So Care Giver might be a Pet Worker, but Accountant probably would not be. So this may be a useful stereotype for the Kennel Management System problem domain, but it may confuse someone outside that domain.

One final warning in regard to stereotypes: do not use them when you really need a superclass/subclass relationship, i.e., when you want to use inheritance (as described in Chapter 1). Stereotypes are about extending UML itself, not about relationships between classes in the code.

Stereotypes: A .NET Perspective

.NET has a few concepts that are not well represented in UML. For instance, .NET supports properties, which look like attributes to outside client code but behave like operations internally. These and other unique .NET features will be represented with stereotypes, as we’ll see in later chapters.

{mospagebreak title=Just Enough Modeling: Analysis, Not Paralysis}

The final pragmatic guideline is to avoid analysis paralysis. If every picture must tell a story, then no picture should be drawn unless it tells a story. Track only the scale and amount of information you need to answer questions. A good design principle, whether for UML or not, is design what you need, and then shut up! Don’t draw diagrams that don’t reveal more about the system than you already know. Eliminate truly trivial diagrams. The principle here is just enough modeling: just enough to answer questions, discover new questions, and answer those, but not to create every diagram you possibly could. That’s too much.

Is it possible to overlook a valuable diagram this way? Of course. But with a good review process, you’ll catch these, when reviewers scratch their heads and look at you funny. They’ll tell you that you’ve missed something, and you’ll insist that it’s trivial. Fine. Prove that it’s trivial; but prove it by drawing the trivial diagram. Either you’re right, and you’ll prove it trivial through use of the new diagram; or you’re wrong, and the new diagram will reveal why. In either case, your communication will improve. But in no case do you say, “It’s obvious! You just don’t get it!”

This rule does not apply, of course, if you’re on a MILSPEC or mission-critical system that demands much more extensive documentation. You have to manage the artifacts of your process, not just the process itself. This rule encourages a focus on artifacts over process. Sometimes, however, the process demands certain artifacts. Part of the review process must include verifying that all legally mandated diagrams are produced.


How Much Can “Too Much” Be?

A student recently asked me, “How many diagrams could we draw, if we wanted to be thorough?” I’d never really thought about that problem before, because I always knew in my heart that the answer was “Too many.” But I realized that this could be a pretty useful question: if some manager did insist on every diagram as part of a “correct” process, how much effort would be involved? So we did some back-of-the-envelope calculations for a small system, based on all the different diagrams that I might draw under certain circumstances. These are necessarily very rough estimates, but they give a pretty good feel for how large such a “correct” process can be:

  • Within the requirements model, assume a top-level “navigational” diagram. 1 diagram.

  • Assume the system is designed for the requirements of approximately 10 different primary actors. That’s enough actors to make me expect that there are at least 2 actor packages—each with a diagram—and a package of actors with a diagram that shows the 2 packages. You’ll often find a “common” package of actors as well, with its own diagram. 4 diagrams.

  • For a really thorough understanding of the problem domain and requirements, you might draw a domain Class Diagram for each actor, including all the other actors and all the domain objects with which it interacts. 10 diagrams.
  • For each actor, you’ll produce a requirements Use Case Diagram that depicts the use cases required by that actor. 10 diagrams.

  • For each actor, you might also want a requirements Use Case Diagram that depicts the domain objects modified or maintained by its use cases. 10 diagrams.

     • As a rough average, each actor will require approximately 5 use
       cases; and of those 5, roughly 2 will have complex relations to
       other use cases, which will require separate diagrams. As
       another rough average, these complex use cases will each be
       related to approximately 2 new use cases. 20 diagrams.

  • For each actor, you’ll have roughly 3 simple requirements use cases, 2 complex use cases, and 2 related use cases for each complex use case, which gives you a total of 9 requirements use cases per actor. For each requirements use case, you’ll draw an Activity Diagram. 90 diagrams.

  • Each requirements Activity Diagram will have roughly 7 activities (action states) in it; and of these, roughly 3 will be complex enough to be subactivity states, each with its own Activity Diagram within it. 270 diagrams.

  • The activities within a subactivity state are usually simpler than the activities in a top-level diagram; but even so, some will have enough complexity to deserve to be subactivity states themselves. Assume this second set of Activity Diagrams have on average around 5 activities, and further assume that 1 out of 10 of these are complex enough to be subactivity states. 135 diagrams.
  • As a rough average, assume each actor is involved with 2 unique domain classes. (Many actors will be involved with more than 2, but there will be some overlap.) This leads to 20 domain classes. That is enough for a domain objects package with approximately four subpackages, along with a diagram for each package. 5 diagrams.

  • To really comprehend each domain class, you can produce a separate diagram to show the class and the classes that are immediately related to it. 20 diagrams.

  • To really understand each domain class and how it changes in response to events, you can produce a Statechart Diagram for the class. 20 diagrams.

  • As a rough average, assume each domain class Statechart Diagram consists of 5 states. Of those, roughly 2 may in fact be composite states, each with its own diagram. 40 diagrams.

  • Within the architectural model, assume a top-level “navigational” diagram. 1 diagram.
  • For each requirements Activity Diagram—including Activity Diagrams nested in subactivity states—you’ll draw an architecture Activity Diagram with swimlanes. 495 diagrams.

  • Within the architectural model, assume a package for interfaces and a package for user interfaces, each with a detail diagram. 2 diagrams.

  • As a rough average, assume that for every 10 architectural Activity Diagrams 1 new, unique swimlane is introduced. (Most Activity Diagrams will involve many swimlanes; but there will be lots of overlap, so assume 1 per 10.) This leads to 50 swimlanes, and thus 50 actors, interfaces, and user interfaces. Because you’re already assuming 10 actors, that leaves 40 interfaces and user interfaces. Those 40 can be grouped into roughly 8 packages, each with a diagram. 8 diagrams.

  • For each interface or user interface, you can draw a protocol for its use, consisting of an average of possibly 2 Interaction Diagrams each. 80 diagrams.
  • Within the architectural model, assume a package for the architectural view of components. This package should include both an Everything Diagram of the overall architecture, as well as a package diagram that shows the packages for the components within the architecture. 2 diagrams.
  • Assume that, on average, each component provides 5 interfaces or user interfaces. That means that, for our 40 interfaces and user interfaces, you’ll need 8 components. For each of these components, you’ll make a new design model, including a top-level “navigational” diagram and a diagram that shows the component and those components immediately related to it. 16 diagrams.

  • For each interface or user interface to a component, assume an average of 4 methods, each with 2 Activity Diagrams (with and without swimlanes). 80 diagrams.
  • Within each component, assume an average of 10 classes. These are enough to justify 2 class packages per component (each with Class Diagrams) and a top-level class package with a diagram that shows the subpackages. 24 diagrams.

  • You can understand each class more thoroughly by drawing a Class Diagram specific to it, showing it in the context of other classes. 80 diagrams.
  • To really understand each class and how it changes in response to events, you can produce a Statechart Diagram for the class. 80 diagrams.

  • As a rough average, assume each class Statechart Diagram consists of 5 states. Of those, roughly 2 may in fact be composite states, each with its own diagram. 160 diagrams.

  • As an average, assume each class has 4 operations. For each operation, you can draw 2 Activity Diagrams: 1 with swimlanes and 1 without. 640 diagrams.
  • The 8 components need to be deployed; so you need 1 logical Deployment Diagram and 1 physical Deployment Diagram. 2 diagrams.

  • Assume an average of 4 nodes in the deployment. For context of each node, you’ll draw 1 logical Deployment Diagram and 1 physical Deployment Diagram. 8 diagrams.

So to analyze and design this fairly simple system—only 50 functions, really— you could potentially draw as many as 2,313 diagrams. Assuming that each diagram takes a half man-hour to create and another half man-hour to revise after review feedback, and that a team of four spends a half hour reviewing each diagram, then that’s a total of 6,939 man-hours spent on diagramming—or, even more frightening, three-and-a-half man-years.

It ain’t gonna happen. This project can’t justify that time expenditure. Only if it’s mission critical, only if lives depend on it, can you justify that much time spent on analysis and design for a system of that size.

So clearly, there’s such a thing as analysis paralysis, such a thing as too much modeling. And experience shows that there’s also such a thing as not enough modeling: not enough to really understand what you’re building. The trick, of course, is just enough modeling.


{mospagebreak title=Summary}

In this chapter, I’ve given you a set of practical “golden rules” to some of the issues that you’ll be dealing with as you begin to analyze your problem domain and develop your model. These are summarized here:

  • Do What Works

    The first rule is self-explanatory. There’s no point rigidly 
    obeying the rules if your model fails to communicate itself to 
    others, so do whatever works for you in your particular 
    situation.
  • The Model Rule

    UML diagrams are like a user interface into your underlying   model. Different diagrams illustrate different aspects of the  model, and so they will contain different information, but the   complete set should present a coherent picture. Completeness   lies in the model, not in a single diagram.

     •  Legible Does Not Mean Pretty

Don’t spend an age getting your diagrams perfect: they only 
need to look good enough to get across the information that 
they are designed to communicate.

  • The MTB Rule (MTB—Minimum Two Brains)

 When you’re working on a new model or idea, always get 
 another member of the team to look at it. They might spot 
 flaws in a model that you didn’t, or help you to correct a 
 diagram. Two or more brains can spark a creative process.

  •  The 7 ± 2 Rule

  The average human brain can only hold 7 ± 2 things in its 
  short-term memory, so cluttered diagrams lead to confusion.
  Simplifying diagrams and reducing the number of elements
  often improves communication. When circumstances demand
  complexity, grouping related elembirtents can aid
  understanding.

  •  The Résumé Rule

        Each diagram should fit onto one standard-sized sheet of paper.

  •  “You just Don’t Get It!” Is Never an Excuse

It’s your responsibility to ensure information is communicated. When there’s a problem, listen to the other people, and find out what they understand and where they think the problem lies. Make sure they can communicate the idea back to you.

    •   Every Picture Tells a Story

Every diagram should tell a story in its own right. All the details on that diagram should contribute to that particular story.

  • The Highway Map Rule

        Your models are maps to your code, so maintain them alongside
        your code, even after it has built. Although they might become
        a little out of step at times, don’t throw them away.

     •   Define Your Own UML with Stereotypes

         UML doesn’t contain a symbol for everything that you need.
         Sometimes it’s helpful to define your own symbols or add extra
         information to elements using UML stereotypes, but always
         check first that there’s not already something defined that you
         can use, or commonly, conventionally used stereotypes.

     •   Just Enough Modeling: Analysis, Not Paralysis

         Your model will never be completely perfect, and sooner or later
         you need to start coding. Learn to recognize when you have
         created a “good enough” model. Holes and other problems will
         show themselves up in review.

We’re going to come back to the process of analysis and design again in Chapter 5, when we look at gathering and analyzing requirements, but because I want to focus on how you can apply modeling and UML in a .NET environment, let’s take some time out first to see what .NET itself looks like as a UML model. That’s going to be the focus of the next chapter.


1.  Scott W. Ambler, Agile Modeling: Effective Practices for eXtreme 
     Programming and the Unified Process
(John Wiley & Sons, 2002)

2.  Jeff Del Papa, and The New England Rubbish Deconstruction
     Society, “The NERDS
Tactical Rules for Scrapheap Challenges
     (Project Management for 10 Hour Projects),”
The New England
     Rubbish Deconstruction Society Web site (
http://www.the-
   nerds.org/
contestant-advice.html
). Along with The MTB
      Rule
, this site has some great practical rules for software
     development and management: “KISS. Keep It Simple, Stupid.”
     “Just  remember:
If brute force doesn’t work, you aren’t using
     enough.” “If you break, you lose.” “MCF:
Mission Critical First.”
     “Test Early, Test Often.” “Leave margins.” “Identify your hidden

     assumptions.” “The machine shop should be a last resort.” “Make
     time for silliness.” “If
something isn’t right—LET THE DIRECTOR
     KNOW RIGHT AWAY!!!” These rules are stated
in the context of a
     high-pressure hardware effort; but the spirit of these rules applies
     to
software as well.

3.  Stephen King, On Writing (Pocket Books, 2002), p. 103. King goes
     on to demonstrate what
he means by writing as telepathy; and he
     makes a compelling (if metaphorical) case.

4.  George A. Miller, Ph.D., “The Magical Number Seven, Plus or Minus
     Two: Some Limits
on Our Capacity for Processing 
     Information,” (
http://www.well.com/user/smalin/miller.html).

5.  Robert A. Heinlein, Stranger in a Strange Land (Ace Books, 1991), 
     p. 266: “‘Grok’ means to
understand so thoroughly that the
     observer becomes part of the process being observed—
to merge,
     to blend, to intermarry, to lose personal identity in group
     experience.” In this
usage, grokking the whole picture is to see in
     it something beyond its individual elements.

6.  Jim McCarthy, Dynamics of Software Development: “Don’t Flip the
     Bozo Bit” and 53 More Rules for Delivering Great Software on Time

     (Microsoft Press, 1995), pp. 30–32. The
communication issue is
     discussed in depth under “Rule #4: Don’t Flip the Bozo Bit.”

     McCarthy’s point in this rule is that assuming that anyone is a
     bozo—i.e., they just don’t
get it—is destructive for that person
     and for the entire team. If they have the skills to make a

     contribution to the team, they have a valuable perspective to
     bring to any problem; and if
you cut off the chance for them to
     make that contribution, you might just as well cut them
loose from
     the team. Never assume your fellow programmers are bozos.

7.   Martin Fowler et al., Refactoring: Improving the Design of Existing
     Code
(Addison-Wesley, 1999)

8.   In Agile Modeling (p. 171), Ambler argues—correctly, I believe—
     that they still ended up with
a notation that is too large and
     bloated for most developers to use completely. Most modelers
use
     only a fraction of the entire language. A large part of the UML 2.0
     effort is to identify the
core” elements of UML.

[gp-comments width="770" linklove="off" ]
antalya escort bayan antalya escort bayan