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
C, then it’s nice to have a sequence
diagram making that clear, but we should also be able to find steps
C explicitly in the code somewhere, e.g.
…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.