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.

Over the years I’ve become less and less enamored with software design tools, what we used to call CASE (computer aided software engineering) tools. That’s not to say that I don’t like and use design diagrams. I make UML diagrams all the time. Mostly class diagrams and sequence diagrams. But generally opt for very simple tools to make my diagrams such as PowerPoint or Visio, rather than full up UML modeling tools. Actually my design tool of preference (which I can’t convince anyone to buy) is a portable whiteboard that can print out hardcopies of what’s been drawn. People seem to be using regular whiteboards and cell phone cameras for this purpose. My artwork and penmanship are awful, and the results weren’t very pretty, but that brings me to my first major point. Design is an activity, not a set of diagrams. The whiteboard is a great tool because it supports the design activity.

I’m not going to try to come up with a comprehensive definition of software design. If anybody could do that, I’d be out of a job along with everyone else who designs software. But I will try to characterize some key features of the activity of software design and how design tools can be obstacles rather than aids.

So what are we doing when we design? We’re weighing various, often conflicting concerns and selecting between solution alternatives to balance them out. These are often called design trades. Design involves making many small decisions, which interact with each other to form a larger solution pattern. These larger solutions need to be evaluated and compared as a whole with regard to all the concerns that drive the design. This is one area where design tools fall down. Most of these tools only attempt to capture the latest design. They can’t track multiple candidate designs, which may share many components and even merge. I would argue that if you’re using a tool to capture the (single) most current design, then you aren’t using it to design, since you’ve already made all the design decisions.

That’s why a whiteboard with a means to make a record of the drawing is a great design tool. You can draw and redraw as quickly as you think of new approaches, and then go back and compare alternatives, combine features, etc. I’ve actually sat through a design session where someone tried to create designs in real-time using a UML tool. The tool brought the process to a standstill. When I use a whiteboard as a design tool, I don’t limit myself to UML diagrams. I sometime use code sketches or fragments, tables, taxonomies and whatever else I can think of to express my designs. I also freely mix UML and other symbology. Tools like Visio allow me to capture this mix in finished diagrams (after that phase of design is done).

While UML modeling tools don’t support the kind of real-time collaboration you get from a bunch of engineers standing around a whiteboard, they have the potential for supporting other modes of collaboration. Unfortunately, they don’t realize this potential. The web has been hugely successful in providing dynamic, collaborative access to complex information. Most UML tools are desktop application that store models in file-based projects. They all provide some mechanism to create diagrams that can be put into web pages, but these are static views. In order for a user to be able to navigate through the model, and customize their views, they need to have access to the desktop application and the project files (most tools don’t support concurrent access). Reviews and other collaborative design meetings usually take place in conference rooms, sometimes at off-site locations. Installing tools and copying project files is not very practical

A tool that truly supports design should store its models as a set of versioned (branching) objects in a shared repository, and have powerful web-based navigation tools with explicit support for comparing versions and alternatives. Model elements should also be web resources (URL) that can be linked from other tools and models. Current modeling tools are firmly stuck in an ‘80s model.

In the next part, we’ll talk about what function design diagrams serve, how tools fail to support and even confuse disparate functions, and the value proposition for design tools (do you get more out than you put in).

Most data repositories start out with great intentions and ambitious goals. If we do a good job of modeling entities and processes in our business and build a system to store and manage this data in a structured manner, then life will be good. We’ll have the tool we need to integrate and manage this information. And at the beginning it all looks good. We write software, populate data, and declare victory.

But after some time passes we often find out that the data in our repository is very sparse, out of date, inconsistent and in many cases just downright wrong. How did this happen? Well the question you should be asking is “how did we notice?” Or even better “why didn’t we notice before?”. You probably discovered the condition of your data in the process of trying to use it. What that means is that at least the parts you are interested in probably weren’t being used (at least not for anything important). If there are folks with a real need to use this data then they will either push for adequate data quality or find their own source for the data.

This leads us to a key insight. The quality of data is determined by its use, not by its source. Without active use, even if you start out with a solid data model and a will to populate with good data, over time the quality will degrade. Maintaining quality data takes effort, there has to be a payoff for this effort.

Active, engaged users for data don’t appear overnight. They must be developed, and cared for. The data repository must provide value to its users. When users begin to depend on data from the repository they become partners and will act to ensure the data quality they need is maintained. At this point the repository takes on a life of its own.

Despite this experience, it is still common to see large, ambitious data repository projects without a clear understanding of how the data will be used, and without an engaged user-base. One way to avoid this trap is to take an incremental approach. Find one use case of high value to users and manageable implementation effort and implement only what is required for that use case. Focus efforts on ensuring that the users get the value they expect (or more) and are fully engaged. Only when this is achieved move on to other use cases. Do not implement any part of the repository without a defined use case, and engaged users.

Following this approach results in a smaller, simpler repository with higher quality data that requires less effort to maintain.

I’m not saying you should abandon modeling. A good model results in a cleaner more flexible design. Just don’t let modeling race too far ahead of meaningful use cases.