Pragmatic Guidelines: Diagrams That Work - Summary (
Page 8 of 8 )
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 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.
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.
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.
/ 11 
