CELEBRATING OUR ANNIVERSARY!
1984-2004: Software Development, ne Computer Language, turns 20!

Send a letter to the editor and tell us your recollections of the magazine: the last 20 years in software, the gurus, the tools, the advances and the challenges. Help make our commemorative September 2004 issue a blast from the past into the future.

http://www.sdmagazine.com/sdonline/letters/

10 TIPS FOR IMPROVING DIAGRAM READABILITY

One of Agile Modeling's (AM) practices is Apply Modeling Standards, the modeling version of Extreme Programming (XP)'s Coding Standards. The basic idea is that developers are more effective when they follow a common set of standards and guidelines, even when the guidance isn't perfect. It's like speaking the same language -- models that are depicted with a common notation and follow effective style guidelines are easier to understand and to maintain. These models will improve communication internally within your team and externally to your partners and customers, thereby reducing the chance of costly misunderstandings. Modeling guidelines will also save you time by limiting the stylistic choices you face, letting you focus on developing software.

All diagrams comprise three basic elements: bubbles (data entities on data models or use cases on UML use case diagrams), lines (associations on UML class diagrams or transitions on UML state machine diagrams) and labels (use case names or roles on associations). As a result, a common set of modeling guidelines applies to most diagrams:

1. Avoid crossing lines. Two crossed lines on a diagram can easily be misread. If you can't avoid crossing lines, draw one so that it "hops over" the other to make their difference explicit.

2. Avoid diagonal or curved lines. Straight lines, drawn either vertically or horizontally, are easier to follow visually. Placing bubbles on diagrams as if they're centered on a graph's grid point, a built-in feature of many software-based modeling tools, makes it easier to connect the bubbles with only horizontal and vertical lines.

3. Draw bubbles of consistent size. The larger a bubble appears, the more important it seems to be. Unless you want that effect, strive to make your bubbles of uniform size. Note that with some modeling tools, bubbles resize automatically based on their contents, so this may be beyond your control.

4. Include white space. White space is the empty area between modeling elements on your diagrams. When bubbles crowd each other, it can be hard to distinguish which labels go with which bubbles and lines, decreasing the diagram's readability. Sometimes, when using a modeling tool, you may be motivated to reduce the white space to print a diagram on a single page. Be aware that you reduce the diagram's usability by doing so -- sometimes taping two pieces of paper together is worth the effort, for readability's sake.

5. Organize diagrams left to right, top to bottom. In the West, people read from left to right and top to bottom. If there's a starting point for reading a diagram, such as the initial state of a state machine diagram or the beginning of the flow of logic on a sequence diagram, place it toward the top-left corner of your diagram and continue appropriately from there.

6. Show only what you have to. Diagrams that have too many details are difficult to read because they're too dense. One of AM's practices is to Depict Models Simply, to include only critical information on your diagrams and not include anything extraneous. Remember the KISS rule: Keep it Simple, Stupid.

7. Avoid esoteric notation. A diagram that uses a wide range of arcane symbols, abbreviations and so on, instead of focusing on the 20% "kernel notation" that does 80% of the job, can be difficult to read.

8. Keep your diagrams small. It's often better to have several diagrams showing various degrees of detail than one complex diagram that reveals everything. A good rule of thumb is that a diagram shouldn't have more than 7 +/- 2 bubbles, because there's a limit on the amount of information that we humans can deal with at once.

9. Focus on content over appearance. Don't succumb to the temptation of adding hours to your modeling efforts by rearranging the layout of your bubbles and lines to improve readability. The best approach is to first focus on the diagram's content -- it doesn't have to be perfect while you're working on it. Once you're satisfied with its accuracy, and have decided that you want to keep it, then you can invest appropriate time to make it look good. You'll save time by not dedicating significant effort to improve diagrams that you may eventually discard as the result of AM's Discard Temporary Models practice.

10. Set and follow effective naming conventions. This ensures consistency within your models and hence increases their readability. Better yet, your diagrams should use consistent and recognizable domain terminology. This is particularly true for domain-oriented diagrams that your project stakeholders are likely to be involved with.

Many of these guidelines seem to be common sense, and they are. Unfortunately, as Mark Twain once remarked, common sense doesn't appear to be very common. Share these ideas with your coworkers, and I suspect you'll quickly discover that your models' usability increases.

A collection of modeling guidelines, including general guidelines such as those described in this newsletter as well as UML-specific tips, appears online at
http://www.agilemodeling.com/style/

My book The Elements of UML Style presents a print version of the modeling guidelines described at the page above. This is a great resource for any team interested in adopting a common set of proven modeling guidelines. For more details, visit
http://www.ambysoft.com/elementsUMLStyle.html

The practices of Agile Modeling are described at
http://www.agilemodeling.com/practices.htm

For a detailed discussion of what an agile model is, visit
http://www.agilemodeling.com/essays/whenIsAModelAgile.htm

The Agile Alliance homepage is the best starting point for anyone interested in learning more about agile software development.
http://www.agilealliance.org

Check out the Agile Modeling mailing list at
http://www.agilemodeling.com/feedback.htm

Get agile modeling training resources at
http://www.agilemodeling.com/training.htm

Terms of Service | Privacy Statement | Copyright © 2024 UBM Tech, All rights reserved.