A good tool should save you work. That is you should get more out of it than you put in. The idea behind most UML design tools is that you put in work up front creating a design model, and then create diagrams that show multiple views or perspectives on the target system. The tool then keeps these views in sync with changes to the model. The models are either constructed by graphically editing diagrams, or are extracted from source code in a process called reverse engineering.
Before we start spewing out lots of diagrams, we should try to determine what their purpose is to be. Are we primarily making diagrams to fulfill some contractual requirement? Is the purpose to get critical feedback from other designers to improve the design? Are the diagrams used to help developers understand the design and guide their work? Or are they detailed specifications that fully describe the software? Of course you might say that you want to use your UML diagrams for all of these, but I’d argue that these uses drive different kinds of diagrams and different features in a design tool.
Let’s start with reverse engineering tools. This begs the question, if we’ve got code, what do we need the design diagram for? Or put another way, what does the diagram do for us that the code doesn’t? The truth is code can be hard to read. Key functionality can be spread over many pages within a compilation unit, or over several units. Source code is where developers live. It’s a pretty dense encoding of information. If a diagram attempts to capture all the detail of the code, it will be even less readable than the code it represents. If you’ve used reverse engineering tools you know what I mean, and the ones I’ve used only attempt to capture structural relationships in a single view.
I look for design diagrams to provide 2 things, clarity and emphasis. Diagrams can often convey larger patterns that are hard to see just by looking at code. Most interesting patterns involve collaborations between multiple interfaces and/or classes. These exist in code but are less obvious and easy to miss. In large, complex programs, there is a lot of code that is fairly straightforward with fairly obvious function and intent. Understanding the design requires understanding the bits of code that are not so obvious. These represent key design features that follow from design trades. Unfortunately they don’t jump up and announce themselves. A good diagram is an opportunity to emphasize essential elements or features in the design and deemphasize or abstract details that are less interesting.
Now what is a trivial detail and what is an essential design feature depends on context. If you are the designer of a utility library then most or all of the details of a String class may be of interest in your design diagrams. If you are designing business object that use strings, then simply identifying an attribute as a string is probably all you need to see. It’s not uncommon to see classes with over 30 operations. If you show all of these on a UML class diagram, you can’t even fit the box on a single page; this doesn’t really result in a useful diagram.
One of my big pet peeves is that UML tools want you to commit to an implementation language even in the analysis phase. For instance, when I’m defining attributes I’m expected to select types from primitives and classes from the target language. OOA methodology says I should probably be using a text description for attributes at this point, but many tools don’t support that. When I want to specify a type, things like number, string or date are usually sufficient. An analysis model doesn’t usually need to be concerned with things like numeric precision. I recently wanted to specify that an attribute was a URL, but had to reference a Java class to do it. I might or might not use a class that supports URL syntax, but the intent to store a URL is pretty clear either way.
Constructing effective diagrams takes time and careful thought. Believe me, I’ve seen many ineffective diagrams. The more clutter you can remove, the easier it is to focus attention on important design elements. So the last thing you need from your design tool is added clutter. Accepted OOD practice is to make member variables private and provide get and set operations to provide public access. In many tools this will end up as 1 attribute and 2 operations on your class diagram. This might be accurate, but it’s not interesting and tends to clutter up the diagram. A good tool should have an option to suppress getters and setters. Another redundant item in class diagrams are attributes that implement associations. We all know that there must be some structure that actually holds the association, but this is not what an “attribute” is supposed to be. If there’s an association on the diagram, the intent is captured, showing the variable that implements it as an attribute is redundant and confusing.
Well that’s enough for this rant. I think there’ll be more coming. Also stay tuned for an article about what makes and effective design diagram.