Making Effective Use of UML

Apparently, architecture, aerospace engineering, and structural engineering do not provide a clear metaphor for software development. We cannot blithely use UML the way those other disciplines use blueprints and models (see Appendix B). So, when and why should we use UML?

Diagrams are most useful for communicating with others and for helping you work out design problems. It is important that you use only the amount of detail necessary to accomplish your goal. Loading a diagram with lots of adornments is possible but counterproductive. Keep your diagrams simple and clean. UML diagrams are not source code and should not be treated as the place to declare every method, variable, and relationship.

Communicating with Others

UML is enormously convenient for communicating design concepts among software developers. A lot can be done with a small group of developers at a whiteboard. If you have some ideas that you need to communicate to others, UML can be a big benefit.

UML is very good for communicating focused design ideas. For example, the diagram in Figure 14-1 is very clear. We see LoginPage deriving from the Page class and using the UserDatabase. Apparently, the classes HttpRequest and HttpResponse are needed by LoginPage. One could easily imagine a group of developers standing around a whiteboard and debating about a diagram like this. Indeed, the diagram makes it very clear what the code structure would look like.

Figure 14-1. LoginPage

On the other hand, UML is not particularly good for communicating algorithmic detail. Consider the simple bubble sort code in Listing 14-1. Expressing this simple module in UML is not very satisfying.

Figure 14-2 gives us a rough structure but is cumbersome and reflects none of the interesting details. Figure 14-3 is no easier to read than the code and is substantially more difficult to create. UML for these purposes leaves much to be desired.

Figure 14-2. BubbleSorter

Figure 14-3. BubbleSorter sequence diagram

Listing 14-1. BubbleSorter.cs

public class BubbleSorter {   private static int operations;   public static int Sort(int [] array)   {     operations = 0;     if (array.Length <= 1)       return operations;     for (int nextToLast = array.Length-2;       nextToLast >= 0; nextToLast--)       for (int index = 0; index <= nextToLast; index++)         CompareAndSwap(array, index);     return operations;   }   private static void Swap(int[] array, int index)   {     int temp = array[index];     array[index] = array[index+1];     array[index+1] = temp;   }   private static void CompareAndSwap(int[] array, int index)   {     if (array[index] > array[index+1])       Swap(array, index);     operations++;   } }

Road Maps

UML can be useful for creating road maps of large software structures. Such road maps give developers a quick way to find out which classes depend on which others and provide a reference to the structure of the whole system.

For example, in Figure 14-4, it is easy to see that Space objects have a PolyLine constructed of many Lines that are derived from LinearObject, which contains two Points. Finding this structure in code would be tedious. Finding it in a road map diagram is trivial.

Figure 14-4. Road map diagram

Such road maps can be useful teaching tools. However, any team member ought to be able to throw such a diagram up on the whiteboard at a moment's notice. Indeed, I drew the one in Figure 14-4 from my memory of a system I was working on ten years ago. Such diagrams capture the knowledge that all the developers must keep in their heads in order to work effectively in the system. So, for the most part, there is not much point in going to a lot of trouble to create and archive such documents. Their best use is, once again, at the whiteboard.

Back-End Documentation

The best time to create a design document that you intend to save is at the end of the project, as the last act of the team. Such a document will accurately reflect the state of the design as the team left it and could certainly be useful to an incoming team.

However, there are some pitfalls. UML diagrams need to be carefully considered. We don't want a thousand pages of sequence diagrams! Rather, we want a few salient diagrams that describe the major issues in the system. No UML diagram is worse than one that is cluttered with so many lines and boxes that you get lost in the tangle, as is (Figure 14-5).

Figure 14-5. A bad but all too common example

What to Keep and What to Throw Away

Get into the habit of throwing UML diagrams away. Better yet, get into the habit of not creating them on a persistent medium. Write them on a whiteboard or on scraps of paper. Erase the whiteboard frequently, and throw the scraps of paper away. Don't use a CASE tool or a drawing program as a rule. There is a time and place for such tools, but most of your UML should be short-lived.

Some diagrams, however, are useful to save: the ones that express a common design solution in your system. Save the diagrams that record complex protocols that are difficult to see in the code. These are the diagrams that provide road maps for areas of the system that aren't touched very often. These are the diagrams that record designer intent in a way that is better than code can express it.

There is no point in hunting for these diagrams; you'll know them when you see them. There's no point in trying to create these diagrams up front. You'll be guessing, and you'll guess wrong. The useful diagrams will keep showing up over and over again. They'll show up on whiteboards or scraps of paper in design session after design session. Eventually, someone will make a persistent copy of the diagram just so it doesn't have to be drawn again. That is the time to place the diagram in some common area that everyone has access to.

It is important to keep common areas convenient and uncluttered. Putting useful diagrams on a Web server or a networked knowledge base is a good idea. However, don't allow hundreds or thousands of diagrams to accumulate there. Be judicious about which diagrams are truly useful and which could be recreated by anybody on the team at a moment's notice. Keep only those whose long-term survival has lots of value.