Here are my notes on the useful parts of UML, for when I write technical documentation for software.

Of course, UML diagrams aren’t the only solution for modeling software systems. Still, they provide a good set of symbols and conventions for those times where I actually have to make a diagram and I don’t want to search the web for How to make flowchart or sequence diagramming method.

Every time I search for a specific diagramming method, I see ten different ways of doing the same thing, depending on which authority on electrical engineering or otherwise you ask. And sometimes, you just want a thing that works, and not more.

Behavioral diagrams

Sequence diagram

These are great for modeling protocol interactions and other asynchronous and concurrent processes where the main focus is on what messages are being sent where. These are very similar to message sequence chart. I was happily using MscGen before, since it has SVG and PostScript output, which is useful for HTML or LaTeX-based typesetting. MscGen is not using a wholly standardized set of diagram elements, though.

State diagrams

Everything I create in my line of work sooner or later becomes a state machine. And most of these state machines go beyond the simple university examples. Take for example a backend server that maintains many active connections to database servers, caches, object storage services, and so on. Each connection state has to be managed accordingly, and not every type of failure stops the world, but some do.

In computer science, nondeterministic finite state machines are defined, roughly, as a Cartesian-like product of all the possible states that can be evaluated ‘concurrently’ (but not really), until the finite state machine hits the one lucky case that gets it to the finish line.

Having nested state machines is similar to that. Instead of defining the state of the server as a Cartesian product of all the sub states, these states can be tracked independently and in an interdependent way, where necessary.

Now that more and more language support algebraic data types (ADTs) as a first-class citizen, modeling ideas as finite state machines and having the type system support this is pleasant. For example, TypeScript has the | and & combinator for types. And Projectify makes heavy use of ADTs in Typescript, in order to implement type-safe state machines.

Activity diagrams

Activity diagrams are standardized flowcharts. Very useful.

The rest, I haven’t tried yet:

• Communication diagram: Looks like a data flow diagram. Never used it, though.
• Interaction overview diagram: This could be useful for nesting any of the other here activity diagrams. Might lead to over-engineering. Never used it.
• Timing diagram: This could have been an electrical engineering-type chart, but for message passing. Unfortunately, it is one of the lesser documented UML diagrams. Never used it.
• Use case diagram: I haven’t made one of these since uni, and they’re not pretty. But in a worse is better fashion, these do offer useful primitives for modeling a business process from 10 km above.

Structure diagrams

These are not really worth it. Perhaps deployment diagrams are worth a look, but for anything else, an entity relationship (ER) diagram is more than enough.

For Django, Django-extensions can create ER diagrams for the models used in an project. Sooooo useful!

As for the remaining structure diagrams:

• Class diagrams: almost no business problem has been solved by defining everything as sub classes. Cardinalities are useful to understand, but ER diagrams are better, since they don’t couple functionality and data.
• Component diagram: I guess, if you created your ControlerProxyInterfaceFactoryManager, you need a large warehouse to package them all neatly?
• Composite structure diagram: We are getting into architecture astronaut territory here. Enough said.
• Deployment diagram: Using standardized symbols for server architecture sounds useful, but I’ve never tried it.
• Object diagram: Never tried it. Showing specific instances of an object sound more useful than a class diagram.
• Package diagram: Never tried it. I could see how this is useful to generate based on the code in a project to visualize and review imports and exports, but not to aid in planning beforehand.
• Profile diagram: The explanation was too dense for me. Can someone explain this to a five year old?

Can we model UML in UML? At least that’s what one of my professors in uni said was the next exciting thing to happen in software engineering (and not figuring out how to prevent the next memory bug in Google Chrome).

These (structure diagrams) aren’t the diagrams you are looking for. Move along.

Summary

As you can see, I am much more interested in modeling the data and then defining as much interesting behavior for that data, as possible. This is a very conscious departure from old academia-brained me, where everything was objects talking to each other and passing messages, and that sounding really cool, like I was creating a multi-agent simulation in my computer and little robots were going about and working for me.

Far from the truth. Leaving the heavy lifting to the data model, and then figuring out how to safely map one piece of data into another for eternity is just so much easier to understand. Now that I am a grumpy developer with a not-yet graybeard, I humbly make way for the next generation of enthusiastic 19-year olds who too are completely fascinated by object oriented programming, because academia and globocorps shove it in their faces.