To Diagram Or Not To Diagram - That Is the Question

Source: otug@rational.com
Date: 17-Mar-98

Problem: Your company has just bought a new expensive CASE tool, supporting state-of-the-art object oriented design notations. Does that mean you should now draw everything before coding it, or are you "allowed" to leave some of the detail out of the diagrams?

Ingemar Lundberg asked:

[...] I've experienced that keeping the drawings in 1:1 with the code has a high cost. [...]

[and in another post:]

[Should I use a CASE tool] as my center of the universe, or else the drawings will be of no value in maintenance? [...]

Here's another angle. In a RAD environment, like Delphi, I see very little value in modeling the forms and dialogs in Rose. However, we use the Observer pattern, this I think is one of the things that should go in to design. When picking up the system for maintenance, I surely would appreciate getting this information up front before looking at the source.

Mark Rodgers replied:

[...] don't put too much effort into making the model exactly reflect every aspect of the code.

[...]

I think that the main purpose of a model is to show the relationships between objects and classes. Therefore, the most important things to show are the associations, dependencies, class public interfaces, and how the objects use each other's public interfaces when they interact. Private methods are IMHO implementation details that can only ever be accessed from one place and can therefore be safely left off the model in many (most) cases.

Robert C. Martin wrote:

How detailed do you get in diagrams? Diagrams are a design and communications tool. You take your diagrams to enough detail that:

You can demonstrate the correctness, robustness, and flexibility of your design. (And this requires quite a bit of detail by the way)
The people who need to code the design, have enough information to produce that code. (The amount of detail depends upon the skill, experience, and insight of the programmer)
The people who need to maintain the system can use your diagrams as a roadmap into the code, and as a vehicle to understand what the code is doing.

Unfortunately, all three of these points are highly subjective. You can't really tell if 2 and 3 have been met until its too late. And it's way too easy to wave your hands around and pretend that you have met 1. Thus, more detail is better than less.

You might use the following heuristic. Continue to create more and more detailed diagrams until you find that when you create them you aren't going back and changing the older ones. At that point the design is probably stable enough.