If you have a career as a software engineer at some point you’ll be asked to diagram a software system. It might be a system you plan to build. It might be to help explain/document a system that has already been built. Or it might be part of an interview question. These days most people seem to have given up on UML and will create a wild mix of arrows, boxes, circles and words. But there’s a lot of other methods that are useful and the best results usually involve a mix. So here are the techniques I’ve found useful in a super quick way.
Boxes and arrows is still a fine technique. Sometimes the other methods don’t fit what you’re trying to describe so just use something simple. Just be consistent! When you draw an arrow does that reflect a flow of data? A dependency? A command? If you need different kind of arrows then be explicit and describe what arrows mean what.
Simon Brown has been promoting his C4 model to all those people stuck at arrows and boxes. It’s a simple way to guide people into breaking down their diagrams and – by extension – their design. I much prefer this over the old 4+1 process, logical, physical , etc. And I don’t mind a diagramming technique that guides toward a design approach.
Use Cases is where I like to start any diagramming. Too often I see people map out high level systems and fail to note where the people are and how they interact. No software system (should) exist without someone benefiting from it. It can help identify when you need everyone in one system and when you can split it up early. It can also help identify any possible MVP version.
A Component Diagram can be a good follow up to the Use Case. There is UML System diagrams that do something similar but I really like the plug and socket style metaphor so that it becomes clear not every socket needs a plug and being able to reuse plugs can simplify things.
I never really used Sequence Diagrams before starting my current role. But the embedded software people use them all the time. It makes sense since we’re often wanting to deal with asynchronous call without tying up big buffers to hold data. So a lot of effort is put into mapping out those sequences over time and where data is stored.
Class Diagrams is the one UML style I remember learning in university but I don’t find very useful. Maybe that’s because I’m now less interested in having deep inheritance or complex classes while doing Test Driven Development.
I wanted to note all these down as I’ve used all techniques at different times and find them all useful for different cases. I never learned all 14 types of UML diagrams and I think most people don’t have the mental space to learn them all. I still have to refer back to this cheat sheet myself to remember the basics and my Use Case Diagrams quickly spawn a creative set of circles, clouds and dotted areas. As long as you include a legend it’s okay to break the rules of that diagramming approach.
Keep on drawing!
Geoff