UML & Design Notation: What the Diagrams Are Good For
The small subset of UML that survived — class, sequence and state diagrams — what each is actually good at, why model-driven code generation failed, and why diagrams that live in a wiki rot while text-based ones in the repo do not.
UML was standardized by the OMG in 1997 to unify three competing notations, and grew to fourteen diagram types plus a model-driven-architecture programme whose goal was generating systems from models. That programme failed — round-trip engineering never worked, the models drifted from the code within weeks, and the tooling cost more than it returned. What survived is a small, genuinely useful vocabulary, and it survived because it communicates between people, not to a compiler.
Three diagram types account for nearly all of the remaining value.
Class diagrams — for relationships, not for classes #
Useful for showing how a handful of types relate. Useless as a picture of a whole system: a class diagram of 200 classes conveys less than the package list.
The notation worth knowing precisely is the relationship arrows, because they are the part people draw wrongly:
| Relation | Notation | Means |
|---|---|---|
| Generalization | solid line, hollow triangle | extends — the subtype is a kind of the supertype |
| Realization | dashed line, hollow triangle | implements an interface |
| Association | solid line | one type holds a reference to another |
| Aggregation | hollow diamond | "has-a", parts can outlive the whole |
| Composition | filled diamond | "owns-a", parts die with the whole |
| Dependency | dashed arrow | uses transiently — a parameter, a local |
classDiagram
class Order {
-OrderId id
-Money total
+add(Item) void
}
class Item
class RateSource {
<<interface>>
+rate(pair) Money
}
class PostgresRates
Order "1" *-- "0..*" Item : composition
Order ..> RateSource : depends on
PostgresRates ..|> RateSource : implements
Multiplicity (1, 0..*, 1..*) is the other part that earns its ink — it is exactly the information a reader needs and the thing a field declaration hides, since List<Item> does not say whether empty is legal.
Sequence diagrams — the most useful of the three #
A protocol over time is genuinely hard to read from source, because the source is spread across the participants. This is the one diagram that regularly tells a reader something they could not get faster from the code.
sequenceDiagram participant C as Client participant A as API participant Q as Queue participant W as Worker C->>A: POST /orders (Idempotency-Key) A->>Q: enqueue OrderPlaced A-->>C: 202 Accepted Q->>W: deliver (at least once) W->>W: dedupe on key W-->>Q: ack
Use them for handshakes, retries, async flows, and anything where ordering or who waits for whom is the question. The failure path is usually more worth drawing than the happy path, since that is the one nobody holds in their head.
State diagrams — the most under-used #
A state machine maps directly onto code, which is why it is the one notation that stays honest: the diagram and the enum plus transition table are the same artifact in two forms. Where an entity has a lifecycle — an order, a payment, a connection, a job — drawing it usually surfaces transitions nobody had considered.
stateDiagram-v2 [*] --> Pending Pending --> Authorized: auth ok Pending --> Failed: auth declined Authorized --> Captured: capture Authorized --> Expired: 7 days Captured --> Refunded: refund Failed --> [*] Refunded --> [*]
The questions it forces: which transitions are missing, which are illegal, and what happens on a retry from each state. That is design work, not documentation.
The other eleven diagram types #
Activity, component, deployment, object, package, timing, communication, composite structure, profile, interaction overview, use case. Occasionally one is the right tool — a deployment diagram for an unusual topology, an activity diagram for a branching approval flow — but none is worth learning pre-emptively, and a team that requires them produces documents nobody reads.
For architecture specifically, the C4 model is the better modern default: four zoom levels (system context, container, component, code), a deliberately small notation, and the explicit position that only the top two levels are worth maintaining by hand.
Keep diagrams where the code is #
The reason architecture diagrams are usually wrong is not that people are careless; it is that a PNG in a wiki has no relationship to the repository and nothing ever fails when it drifts.
Text-based diagrams — Mermaid, PlantUML, Structurizr DSL — fix the mechanics: they live in the repo, they appear in diffs, a reviewer sees the diagram change alongside the code change, and no separate tool is needed to edit one. That does not make them automatically correct, but it puts them on the same review path as everything else.