UML Best Practice: 5 rules for better UML diagrams
Following these 5 rules will make your UML diagrams easier to understand, cleaner, and more consistent.
Although that has no effect on the actual model, it will improve the communication with the stakeholders.
Rule 1: Less is more
Large diagrams containing heaps of elements actually convey less information then small focussed diagrams.
When reading such a large diagram your audience will not know what to focus on, and since there’s too much on there to actually pay attention to all elements, they will quickly give up trying altogether.
Show up with a diagram like this at your stakeholder, and you will have already lost his/her attention even before you start talking.
The diagram above is a good indication of how much, or how little, you should put on a diagram. My rule of thumb is that you need to be able to print the diagram on a single A4 sheet while keeping things readable.
Rule 2: No Crossings
This is a fairly common and well known rule. Try to avoid any two lines in your diagram to cross each other.
Uncrossing lines in your diagram sure make it more readable and understandable, but there’s more to it then that. If you are unable to uncross the lines on your diagram then that is a sign that
- a) there’s too much on the diagram (see rule 1 Less is more)
It might be that you are showing two different aspects of the model in one diagram. In that case it might be better to create two different diagrams, each focused on one aspect.
- b) there is some kind of design flaw in your model
For some reason well designed models don’t have the crossing lines problem. I have no idea why or what it is exactly, I just noticed that a lot of the times, when I’m unable to “uncross” all the lines in a diagram, I discover a design flaw that, when fixed results in a diagram without crossing lines.
Rule 3: Orthogonality
It seems like a small thing, but making the lines in a diagram go only horizontal or vertical, and having all only right angles makes a diagram look better instantly.
The diagram below is uses a direct style for its connectors. they all go directly from one element to the other with a straight line.
The mere fact that the lines have all kinds of angles makes the diagram look a lot messier, and less understandable.
Below here again the same diagram, but now with all connectors styles set to orthogonal.
Exceptions to this rule are (for me) note links and all relations with use cases. For some reason they look better with a direct style.
Rule 4: Parents Up
When drawing generalization or realization hierarchies on a diagram always make sure the parent elements are higher then the child elements so the arrows always point upwards.
This rule is pretty intuitive for most UML modelers. Only now and then I encounter diagrams that don’t follow this rule and have their hierarchies upside down.
Diagrams like this, where the generalization arrows point downwards are harder to read. For some reason it takes a greater mental effort to understand this then when the arrows all point upwards.
In case you have multiple elements all descending from the same parent, it is recommendable to show the hierarchy in a vertical tree style.
Rule 5: Tidy Up
I realize this sound like a nagging mom, but for crying out loud: Tidy Up!
If you want to convey the message that your analysis is a well thought trough construction that will solve your stakeholders problems then you better show up with a nice and clean diagram.
When tidying up think about
- Aligning elements, either by one of their sides (e.g Top) or by their centers. The latter works best when aligning vertically
- Make elements the same size where possible
After tidying up the diagram looks a loot better
Now remember, following these diagramming rules will not make you a better analyst, nor will it result in better UML models.
But it will allow you to make a better impression when trying explain the fruits of your hard labor to your stakeholders. You will need less time explaining diagrams, and you will be able to spend more time focusing on the actual content.
I agree with the rules here but I wanted to add that the most important rule is to focus the diagram on the intended audience. I am not a big fan of the UML class diagrams with inheritance, composition and aggregation arrows because they only tend to be understood by the techies. When trying to depict the information model for business users I prefer to only show the entity names and use the ERD crow-feet etc to show the relationships.
@Rob As I mentioned in my comment, for information models I prefer the easy to understand ERD crow-feet notation. Whilst kite9 doesn’t look bad, I am just not sure there is a need for yet another notation and tool.
HI Geert,
I quite like the crow’s feet notation too…. in your UML diagrams though you are using the UML cardinality symbols though, which are different, right?
Only problem with crow’s feet as I see it is that it introduces a lot of mystery meat into the diagram (i.e. symbols that most people don’t understand), whereas putting 0..n next to the link I think is a bit more obvious.
What do you think?
Hi I like this kind of best practices. This is helpfull for everybody and makes indeed the diagrams better understandable.
Rob,
Don’t get confused, but there are two Geert’s here 🙂
Geert Claes, who made the comment about the crows feet, and me, the article author.
And for the record, I stick with the standard UML notation.
Indeed, it doesn’t happen often that my name gets confused with someone else 🙂
To add to the op’s record, I am the one who prefers the crows-feet over the UML notation.
Rob
There’s nothing in the E-R notation preventing you from showing the cardinalities (0..n etc.) as well as the crow’s feet. Some of the dedicated data modelling tools on the market support this. Does EA allow you to show both?
well, thanhks very detailed article, very useful!
I know this article is only about layout, but just in case you didn’t realize, the diagrams are not strictly speaking UML compliant:
a) they use the diagram heading “class”. According to the UML specification, this denotes a composite structure diagram. But these appear to be class diagrams representing packages (in which case the header at top left should say package P not class P)
b) the placement of superclass names in the top right of the class compartment is non-standard
You also have a structural invalidity in the top diagram: you have Kernel::Property with 2 mandatory composite owners, class and datatype. They are mandatory since the default multiplicity is 1..1. It’s invalid since there’s a ‘built in’ rule that any instance can have at most one owner. Due to the mandatory multiplicity any instance of Property must be owned by both 1 Class and 1 Datatype, However that would break the “one owner” rule. The solution is to make class and datatype 0..1. You could even have an ‘xor’ constraint between them.
It’s not invalid but unusual to see associations with “navigability” arrows at both ends – normally people elide them completely. I’d be interested in your reasons for this style. And how, indeed, you make use of navigability in modeling – since at UML 2 its meaning is about “efficient access”.
Geert,
Thanks for the 5 rules. I have used them for nine years and what you mentioned here are correct.
Richard
Good Writeup. Very clear and good explanatory steps. Will recommend it.
b.t.w.: do you know how to make all connectors in a diagram orthogonal?
Thanks,
I don’t think you can out of the box. There’s an “old” add-in that supposedly does this, but I’ve never tried it myself:
http://eautils.codeplex.com/
The good thing is that it’s open source, so if you wanted that you could use the code for your own add-in.
Geert
As with all “rules” they have to be considered in context. Instead of labeling them “wrong”, I would, instead, label them “Less Effective”
For example, rule 1, “Less is More”, trades complexity WITHIN a diagram to complexity AMONG several diagrams. This is usually the right decision, but with some audiences and with some purposes, a complex diagram is more effective, especially if the modeler follows your other rules. Certainly one complex diagram could be better than 10 simple diagrams that don’t give the big picture. A typical circumstance is a diagram working as a context diagram, showing all the external interfaces to a system. As a reference diagram, especially when blown up and put on the wall, it could just be the right way of expressing the information.
Always consider the audience and purpose for each diagram
Rule 2 also has exceptions.
When there are 5 or more elements that are completely connected (every element connects to every other element), it is topologically not possible to avoid line crossing.
In addition, in other structural diagrams, e.g., in activity diagrams, it is difficult to avoid line crossing if you also have other conventions — like inputs from the left and outputs to the right, and even simple control (decision/merge, fork/join) constructs on the diagram.
Yes, in my role as model reviewer, I always strongly recommend avoiding line crossing, but allow it when it’s better than the alternative.
Rule 3 also has some rare exceptions. There are circumstances where the diagram emphasizes a central element, with many dependent elements. This is especially true when the central element is not rectangular. In such cases, the direct connection through the center will look the best.
BTW, UML does not normally represent “cardinality” . In UML and related modeling languages the 0..n notation is consider “multiplicity”, the range of possible “cardinalities” .
In UML Object or Instance diagrams, the cardinality can be represented as it is typically a single value. In a UML class diagram, a Star can have 0..* Planets, on a UML object diagram, the Sun (and instance of Star) has exactly 8 Planets. The 0..* is the multiplicity range and the 8 is the cardinality.
I really appreciate your stuff in here. I was not really caring about theese issues. My colleauges were mad at me. So i’ll be designing tidier.
Hi if i have a class diagram for a check-in system for automatic check-in, express lane check-in and normal check-in with 17 classes(assuming database has already been created) is it consider too much?
17 classes is probably pushing the upper limit.
Can you still print it on a A4 and still read all the info? If not you might consider creating a diagram per type of check-in.
These guidlines are very useful for me to model SysML/UML diagrams which can be understood with less effort by other non-technical collegues. But there are some exceptions depends on the complexity of the diagram.
In some diagrams it is so difficult to avoid the crossing lines.
Hi, what is the diagram software / tool you used to create these diagrams? Its it creately ?
No, I’m using Enterprise Architect from Sparx Systems.
How are such rules related to the design principles and general notions of SW design?
They are not directly, but you’ll find that messy UML diagrams often lead to bad designed software as well.
If the UML diagram can’t be made to look pretty and balanced, then that somehow indicates that there is something wrong with the design of the software.
Thank you so much. Thought that I was the only one who’s obsessed about the ordering and perfect lining :).
What about the rest rules of uml diagram?