Friday, December 13, 2013

Drawing UML Diagrams

Recently we've introduces a CASE tool in our company for being able to model before we code. From my own experience I have the perception, there are for more bad diagrams out in the world than diagrams that really help understanding the problem or the solution. This made me think about best practices for drawing UML diagrams which I could share with my colleagues, that I would also like to share with the rest of the world.

Without reading what's already available in the net (i.e. the UML Best Practices: 5 rules for better UML diagrams) I came to the following list of principles you should consider when drawing diagrams:
  • Be Creative. Designing is a creative task, there is no right or wrong. Three designers might produce four different solutions for the same problem which all work well. Sou you also might consider different ways of expressing certain aspects. Take your time to step back and ask yourself, will my intended audience understand, what I want to express? Or why not?
  • Focus. People tend to overload a diagram. Concentrate on expressing only one aspect. Design a racing car or truck, but not both (and not even think about a boat). Isolated aspects should be expressed in a separate diagram, the connection between two aspects can be captured in an overview diagram. Similar to digital photos: more diagrams do not cost more money - but more time to understand will do.
  • Keep it Simple. From the psychology of perception, there is a limit of how many elements one could easily recognize without having to think too much. This limit is different for each individual but as a rule of thumb it lies around 10 elements. So if your intention is, to make your audience understand the problem as quick as possible (i.e. in a presentation), reduce the number of element to below 10. If your problem is not distributable across multiple diagrams or the audience will has the freedom to take time to understand - which both are rarely the case - you could have more than 10. But always be sure about the consequences, the time to understand will increase much. The number of elements on a diagram is no measure for complexity of the problem but for the inability to understand the real problem.
  • De-Clutter. Remove everything that is not relevant. While 'Focus' and 'Keep it Simple' aims at reducing the number of elements (i.e. Classes) De-Cluttering aims at reducing the number of additional information, such as labels, cardinality information, visible associations. In model-centric modelling tools you create a datastructure with diagrams showing the structure from different perspectives, this means, that removing elements and additional information from a diagram does not mean, you remove them from the structure. Labels of an association specify a certain role, this role might be totally irrelevant for the diagram you're drawing. Same for the cardinality or additional associations, like package membership. So always check, does the information help to quickly understand the concept your depicting? If yes, keep it, if not remove it.
  • Order. Avoid Chaos. A viewer of a diagram should be naturally guided through the diagram. There should be a natural reading order that supports the understanding of the diagram. Arrange the elements according to their meaning (front/back, client/server, consumer/producer) starting top-left in the directions (or combinations of them): left-to-right, top-to-bottom, outside-in or inside-out (starting the the center). Avoid crossing lines. In cases where it is not avoidable, use jump-links. Sometimes it helps to simply rearrange elements to avoid crossings. Use diagonal lines only, where it suits. I prefer diagonal lines in use-case diagrams, while using orthogonal lines in more technical diagrams (class, deployment,...). 
  • Compress. Reduce the white space as much as possible. Arrange the elements closer to each other, reduce their size as much as possible. Avoid diagrams that are too big so you either have to scroll or zoom out to see everything.
In summary, a checklist of criteria for good diagrams could be:
  • looks "nice"
  • arrangement in logical-order
  • element count < 10
  • diagram-size < display-size (without zooming)
  • more orthogonal lines, less diagonal lines
  • no crossings 
And one more advice. When drawing UML diagrams, be sure about the semantics of the (graphical) notations. Don't just use certain shapes because they look nice, to someone familiar with UML they might easily reveal whether you understand UML or not.

    No comments: