When to Diagram and When to Stop

When coming to the UML section of Uncle Bob's PPP book, a sense of dread overcame me.  I've read several books on UML in the past it always seemed to be overkill for what I wanted to do.  I have to admit I expected Bob to use the UML section to preach to us about how we should all be writing UML documents before we code.  This was far from the case.  Actually, I think he gives some very good advice about how to use diagrams in general, especially in an agile environment.

The recurring theme throughout the chapter was that you typically do not want to hang on to diagrams.  In most cases, they should be drawn on a whiteboard and then discarded once the ideas behind the diagram have been communicated.

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.

One of Uncle Bob's points that I really liked was that you should never let the diagram get to far away from code.  The purpose of diagrams are to help in writing code.  When a group of developers stand around a whiteboard looking at a diagram, they should all know how the diagram translates to code, otherwise you are building castles in the air.

I also liked the following lists Uncle Bob created for when to diagram and when to stop.

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