UML sequence diagrams

A sequence diagram answers one question precisely: what happens, in what order, between whom. It is the diagram you draw when two people disagree about which service calls which, or when a flow crosses four systems and nobody has the whole path in their head.

The layout does all the work. Participants sit across the top. Time runs downwards - not left to right, and not to scale. A message lower on the page happens after a message higher on the page, and that is the entire reading rule.

Three pieces of furniture, and everything else is a variation on them.

A lifeline is the head at the top plus the dashed vertical line running down from it. The head names the participant. It can be a class name, an object (: Checkout), an actor drawn as a stick figure, or a role with a stereotype like «boundary» or «control». Whichever you pick, be consistent down the whole diagram.

An activation bar - sometimes called an execution occurrence - is the thin rectangle laid over the lifeline. It marks the span during which that participant is doing something. Nested bars mean a participant called back into itself. Activations are optional in UML, and they are worth drawing: they make it obvious that Checkout is still waiting while the gateway works.

A message is the horizontal arrow. Its style says what kind of call it is, and that is the part worth memorising.

The filled-versus-open arrowhead distinction is the one that carries real weight. It is the difference between "the caller is now blocked" and "the caller moved on", and it is the single most useful thing a sequence diagram tells a reader about a distributed system.

Real flows have conditions and repetition. UML handles both with a combined fragment: a box drawn around a run of messages, with an operator in a tag at its top-left corner.

• alt - alternatives. Split by a dashed line into compartments, each with a guard in square brackets. Exactly one runs. This is an if/else.
• opt - optional. One compartment with a guard; it runs or it does not. This is an if with no else.
• loop - repetition. The guard gives the condition or the bounds, as in loop [1..*] or loop [while more pages].
• par - parallel. Compartments run concurrently, in no guaranteed order.
• ref - a reference to an interaction defined on another diagram. This is how you keep one sequence diagram from growing to three pages.
• critical - a region that must not be interleaved with anything else.

A sequence diagram is also the most effective UML artefact for reviewing a design before it is built, because it forces the awkward questions into the open. What happens if the gateway times out? Who retries? Is that call blocking? You cannot draw the diagram without answering them.

1. Every arrow drawn solid-filled. If everything looks synchronous, the diagram has thrown away its most useful distinction. Use open heads for fire-and-forget.
2. Reply arrows for everything. A reply to a synchronous call is often implied and can be omitted. Draw it when the returned value matters.
3. Mixing abstraction levels. A lifeline for a whole payment platform next to a lifeline for a single helper class. Pick one altitude.
4. No error path. The happy path alone is the least interesting half. An alt with the timeout branch is what makes the diagram worth reviewing.
5. Twenty lifelines. Past roughly seven the diagram stops fitting on a screen and starts being scrolled rather than read. Split it and use ref.