Software architecture and UML
You are taking over software that someone else wrote. There is hardly any documentation, the comments are out of date, and the people who knew the code have left. Even so, you are expected to fix bugs and add new features – and soon.
Reading the code file by file takes a long time and mostly yields details. You make faster progress with a picture of the whole: Which parts exist, how do they fit together, and what happens in which order? This is exactly what UML, the Unified Modeling Language, is for.
Structure and behaviour: two views of the same code
UML defines fourteen diagram types. To get into unfamiliar code, a few are enough. They fall into two groups: structural diagrams show the blueprint, behavioural diagrams show the flow.
| Diagram type | View | Question it answers |
|---|---|---|
| Class diagram | Structure | Which classes exist, and who knows, owns or inherits from whom? |
| Package diagram | Structure | Which building blocks, such as DLLs or namespaces, depend on each other? |
| Sequence diagram | Behaviour | Who calls whom, and in which order? |
| State diagram | Behaviour | Which state is a process in, and what moves it on? |
| Activity diagram | Behaviour | Which activities follow each other, and where does the flow branch? |
How to proceed
- Find the entry points. Where does the program start? In desktop software these are commands, menu items, buttons or events. Write down the three to five workflows that really matter for your task.
- Draw the structure. Start with a class you already know and follow its relationships. Only draw the classes that belong to your workflows.
- Draw the behaviour. Step through each important workflow in the debugger and record it as a sequence diagram: one box per object involved, one arrow per call, with time running from top to bottom. If a workflow has several steps or modes, add a state diagram.
- Put the diagrams side by side. Now you see what the code alone does not show: classes that do the same thing, workflows that calculate the same data several times, and dependencies that point in the wrong direction.
- Talk to the experts. Show the diagrams to the people who use or support the software. Five boxes on a whiteboard often clarify in minutes what takes days in the code.
Reading class diagrams: the lines make the difference
A class is a box with up to three compartments: name, attributes and methods. The interesting part is between the boxes. A solid line means “knows”. A hollow diamond means “has”: the part can live without the whole, like a tree without a forest. A filled diamond means “consists of”: the part lives and dies with the whole, like a branch with its tree. A hollow triangle stands for inheritance, meaning “is a”. A dashed arrow means “uses”.
Three rules help when reading: the diamond sits at the whole, the triangle at the superclass, the arrowhead at the class being known. The ends of a line carry multiplicities such as 1, 0..1 or 0..*.
From practice: calibration in 3 steps instead of 5
A large international sensor manufacturer asked us to take over the calibration software for laser scanners with a mirror wheel. The previous service provider had stopped working on it. The source code was barely readable and partly obfuscated. Calibration consisted of five steps that system installers, integrators and support staff carry out worldwide for every installation.
We examined the code step by step and modelled both the static structure and the dynamic workflows in UML. It quickly became clear that several calibration steps overlapped. This was hard to see in the code, but obvious in the diagram. We then re-aligned the steps mathematically and removed the redundant ones. Today, calibration takes three steps instead of five. Because it is carried out so often worldwide, this saves several thousand working hours per year.
Typical mistakes
- Everything in one picture. Nobody reads a diagram with forty boxes. Three small diagrams, each answering one question, work much better.
- Generating only. Many tools generate class diagrams from code. That is a good starting point, but not yet an overview. The overview comes from selecting and leaving things out.
- Structure only. A class diagram shows what exists, not what happens. Duplicated work in workflows only shows up in a sequence or state diagram.
- The diamond on the wrong side. The diamond belongs to the whole. If it sits at the part, the leaf suddenly owns the tree.
- Composition where there is only a reference. Not every reference in code means ownership. Check who creates an object and who releases it.
- Diagrams that go stale. A diagram that no longer matches the code is worse than none. Keep it small and keep it up to date.
How we help
- We analyse unfamiliar or legacy code and make it understandable with UML: Quality review and code review.
- We plan new software with UML before the first line is written: UML in software planning.
- Your team learns to read and draw UML diagrams: UML training in the Cadida shop.
- You have taken over code and don’t know where to start? Arrange an initial consultation.
Sources: Ebi F. Eilber, AutoCAD .NET API (technical book, expected to be published in 2027), chapter “Reading UML”; case study “Calibrating mirror-wheel laser scanners: 3 steps instead of 5”, Cadida case studies.
kununu