Here are my notes on the useful parts of UML. Creating diagrams is an important part of technical documentation.
As many know, UML diagrams aren’t the only solution for modeling software systems. Still, they provide a good set of symbols and conventions. I often make diagrams for software documentation. I don’t want to search the web for How to make flowchart or sequence diagramming method every time.
I often need to look up how to create a specific kind of diagram. For each diagram, there are at least ten different sets of symbols. It depends on which authority on what kind of engineering you ask. Sometimes, you just want a thing that works, and not more.
Behavioral diagrams
Sequence diagram
These are great for modeling protocol interactions. They’re also good for modeling asynchronous and concurrent processes. They help understand who sends what messages to whom. Sequence diagrams look a lot like message sequence charts.
I enjoyed using MscGen to create message sequence charts before. It supports SVG and PostScript output. This is useful for HTML or LaTeX-based typesetting. MscGen’s set of diagram elements isn’t entirely standardized, though.
State diagrams
Everything I create in my line of work sooner or later becomes a state machine. Most of these state machines go beyond simplified university examples. Take for example a backend server that can hold many active connections. These may be connections to database servers, caches, or other services. The server needs to manage each connection state on its own. Not every connection failure stops the world, but some failures do.
Nondeterministic finite state machines are like a Cartesian product of all the possible states that can be evaluated ‘concurrently’. Such a finite state machine evaluates all these possible states at the same time, until it hits a final state.
Nested state machines in UML resemble these finite state machines. They allow you to track states independently. If necessary, these states can also depend on each other.
More and more languages support
algebraic data types
(ADTs) as a first-class citizen these days. A type system that supports
modeling ideas as finite state machines is pleasant to use. For example,
TypeScript has the |
and &
combinator for types. And
Projectify makes heavy use of ADTs in TypeScript,
to create type-safe state machines.
Activity diagrams
An activity diagrams is a standardized form of flowchart.
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. This 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. Worse may be better, though. At least they get the job done. They offer useful primitives for modeling a business process from a bird’s-eye view.
Structure diagrams
These aren’t worth it. Perhaps deployment diagrams are worth a look. For anything else, an entity relationship (ER) diagram is enough.
For Django, Django-extensions can create ER diagrams for the models used in an project, a useful feature.
As for the remaining structure diagrams:
- Class diagrams: no one solves business problem by making a lot of sub classes. Cardinalities are useful to understand, but ER diagrams are better. ER diagrams don’t couple functions and data.
- Component diagram: Maybe you are creating a lot of ControlerProxyInterfaceFactoryManager classes. Perhaps this gives you a large warehouse to package them all in a neat way?
- Composite structure diagram: This is architecture astronaut territory. Enough said.
- Deployment diagram: Using standardized symbols for server architecture sounds useful. 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. This may be useful to generate based on an existing projects. It can help review imports and exports. I don’t see how this is useful for planning, though.
- Profile diagram: The explanation was too dense for me. Can someone explain this to a five year old?
Can you model UML in UML? At least that’s what one of my professors in uni said. He would call it the next exciting thing to happen in software engineering. Not, 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 conscious departure from old academia-brained me.
It used to be that everything was objects talking to each other and passing messages. It used to sound cool. As if I was creating a multi-agent simulation in my computer and little robots were going about and working for me.
Far from the truth. Leave the heavy lifting to the data model. Then, figure out how to map one piece of data onto another. It’s 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, fascinated by object oriented programming. Academia and globocorps shove object oriented programming in everyone’s face.