The code should be a sequence diagram too

I love sequence diagrams and other kinds of visual documentation of a system, especially ones that are committed in the repo alongside the application code.

PlantUML is a nice tool for this as there’s a simple mark-up language for creating and editing diagrams which sits nicely in a Git repo. You can commit and review changes to diagrams as you do with the rest of the code.

Diagrams are a kind of comment, though, and so really they should only supplement the code and not be a substitute for readability or clarity of the application code itself.

So if some process has steps A, B and C, then it’s nice to have a sequence diagram making that clear, but we should also be able to find steps A, B and C explicitly in the code somewhere, e.g.

processOrder() {
	initialiseOrder();
	validateOrder();
	submitOrderToPartnerSystem();
	submitOrderToOtherPartnerSystem();
	finaliseOrder();
}

…for whatever particular steps we have in that process.

This is surprisingly rare across codebases. A big factor in that is that it can be quite hard to achieve. High-level business processes are often not implemented on a single machine or data-centre, let alone within a single function call in a single OS process. It’s a shame, though, as the clarity of a codebase would be increased dramatically if the code actually was a recipe describing what it does, as we’re often advised it should be.

If there is any opportunity to get a meaningful description of a high-level process explicitly in the code, it’s well-worth pursuing for the benefit it brings to design, maintenance and modification.

As with many software design principles, merely bearing the concept in mind can still be a guide to better designs, even if we don’t fully achieve it in every case.