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.

Everything above sits inside a box that most diagrams draw and few readers notice: the interaction frame, a rectangle around the whole diagram with a tag in the top-left corner reading sdand the interaction's name. It looks like decoration and it is not - it is what gives the interaction a name, which is what makes ref possible. Without it you cannot cut a long flow into pieces, which means every flow has to fit on one page.

The fragment list in the previous section is the working set, not the whole set. Four more operators exist and three of them earn their place occasionally: break abandons the rest of the enclosing fragment when its guard holds, which is the natural shape of an early return on error; strict forces the order of its compartments where plain seq leaves them loose; neg marks an interaction that must not happen, which is a way of writing a negative test into a picture. assert, ignore and consider belong to formal specification work and are safe to skip until something forces them on you.

The most valuable thing a sequence diagram does is not documenting the happy path. It is that once the happy path is on a page, the failures become countable - and a flow crossing four systems has a lot more of them than anybody estimates from memory.

Walk down the diagram and ask three questions of every message, in order. The answers are your extension paths, and each one is either a fragment you should draw or a decision somebody needs to make.

1. What if there is no reply? Every synchronous message is a place the caller can block forever. Somewhere there is a timeout value; if nobody in the room knows what it is, that is the finding. Draw it as an alt with a [timeout] guard, and the number goes on the diagram where it can be argued with.
2. What if the reply is a failure? Distinct from no reply, and treated identically by an alarming amount of production code. A declined authorization and a dead acquirer need different handling, and the diagram is where that difference becomes visible.
3. What if this is delivered twice?Ask it of every asynchronous message, because queues redeliver and clients retry. If the answer is "the customer is charged twice", you have found the idempotency requirement that was not in the ticket.

Then read the diagram once more, backwards, for the question the forward pass never catches: what has already happened that now has to be undone?A failure at the fourth message leaves the first three's effects in place. That is the compensation logic, and a sequence diagram is the cheapest place in the world to discover you need some.

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.