When and How to Draw Diagrams


Drawing UML diagrams can be a very useful activity. It can also be a horrible waste of time. A decision to use UML can be either very good or very bad. It depends on how, and how much, you choose to use it.

When to Draw Diagrams and When to Stop

Don't make a rule that everything must be diagrammed. Such rules are worse than useless. Enormous amounts of project time and energy can be wasted in pursuit of diagrams that no one will ever read.

Draw diagrams when:

  • Several people need to understand the structure of a particular part of the design because they are all going to be working on it simultaneously. Stop when everyone agrees that they understand.

  • You want team consensus, but two or more people disagree on how a particular element should be designed. Put the discussion into a time box, then choose a means for deciding, such as a vote or an impartial judge. Stop at the end of the time box or when the decision can be made. Then erase the diagram.

  • You want to play with a design idea, and the diagrams can help you think it through. Stop when you can finish your thinking in code. Discard the diagrams.

  • You need to explain the structure of some part of the code to someone else or to yourself. Stop when the explanation would be better done by looking at code.

  • It's close to the end of the project, and your customer has requested them as part of a documentation stream for others.

    Do not draw diagrams:

  • Because the process tells you to.

  • Because you feel guilty not drawing them or because you think that's what good designers do. Good designers write code. They draw diagrams only when necessary.

  • To create comprehensive documentation of the design phase prior to coding. Such documents are almost never worth anything and consume immense amounts of time.

  • For other people to code. True software architects participate in the coding of their designs.

CASE Tools

UML CASE tools can be beneficial but also expensive dust collectors. Be very careful about making a decision to purchase and deploy a UML CASE tool.

  • Don't UML CASE tools make it easier to draw diagrams? No, they make it significantly more difficult. There is a long learning curve to get proficient, and even then the tools are more cumbersome than whiteboards, which are very easy to use. Developers are usually already familiar with them. If not, there is virtually no learning curve.

  • Don't UML CASE tools make it easier for large teams to collaborate on diagrams? In some cases. However, the vast majority of developers and development projects do not need to be producing diagrams in such quantities and complexities that they require an automated collaborative system to coordinate their diagramming activities. In any case, the best time to purchase a system to coordinate the preparation of UML diagrams is when a manual system has first been put in place, is starting to show the strain, and the only choice is to automate.

  • Don't UML CASE tools make it easier to generate code? The sum total effort involved in creating the diagrams, generating the code, and then using the generated code is not likely to be less than the cost of simply writing the code in the first place. If there is a gain, it is not an order of magnitude or even a factor of 2. Developers know how to edit text files and use IDEs. Generating code from diagrams may sound like a good idea, but I strongly urge you to measure the productivity increase before you spend a lot of money.

  • What about these CASE tools that are also IDEs and show the code and diagrams together? These tools are definitely cool. However, the constant presence of UML is not important. The fact that the diagram changes as I modify the code or that the code changes as I modify the diagram does not really help me much. Frankly, I'd rather buy an IDE that has put its effort into figuring out how to help me manipulate my programs rather than my diagrams. Again, measure productivity improvement before making a huge monetary commitment.

In short, look before you leap, and look very hard. There may be a benefit to outfitting your team with an expensive CASE tool, but verify that benefit with your own experiments before buying something that could very well turn into shelfware.

But What About Documentation?

Good documentation is essential to any project. Without it, the team will get lost in a sea of code. On the other hand, too much documentation of the wrong kind is worse because you have all this distracting and misleading paper, and you still have the sea of code.

Documentation must be created, but it must be created prudently. The choice of what not to document is just as important as the choice of what to document. A complex communication protocol needs to be documented. A complex relational schema needs to be documented. A complex reusable framework needs to be documented. However, none of these things need a hundred pages of UML. Software documentation should be short and to the point. The value of a software document is inversely proportional to its size.

For a project team of 12 people working on a project of a million lines of code, I would have a total of 25 to 200 pages of persistent documentation, with my preference being for the smaller. These documents would include UML diagrams of the high-level structure of the important modules, ER (Entity-Relationship) diagrams of the relational schema, a page or two about how to build the system, testing instructions, source code control instructions, and so forth. I would put this documentation into a wiki[1] or some collaborative authoring tool so that anyone on the team can access it on the screen and search it and change it as need be.

[1] A Web-based collaborative document authoring tool. See http://c2.com and http://fitnesse.org.

It takes a lot of work to make a document small, but that work is worth it. People will read small documents. They won't read 1,000-page tomes.




Agile Principles, Patterns, and Practices in C#
Agile Principles, Patterns, and Practices in C#
ISBN: 0131857258
EAN: 2147483647
Year: 2006
Pages: 272

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net