I was looking through job listings and I noticed one of the positions requested experience in creating state machine diagrams as a frontend or full-stack developer.
It made me wonder, how often do devs actually take the time to diagram their state or state machines? Do you have any examples you can share from your projects if so?
Top comments (6)
At my last job I developed a criteria-driven state machine for determining the user's current position in a guided accessibility testing questionnaire. That involved a lot of diagramming, although for the most part I had the luxury of being able to ignore the actual content and prove the system out on a smaller idealized set of states (our UX designer, meanwhile, had to draw each guided test program out in full).
There is a diagram called grafcet (see example of traffic light below made with grafcet.online) - not many in traditional software know because it's used in complex real time automation in industry - that can help you have a clear vision of states
I draw it to follow this Ruby tutorial rubyguides.com/2018/12/state-machines
I also use it to create interactives notes or cheatsheets see examples:
dev.to/lepinekong/figma-plugin-api...
Modeling state transitions used to be big important step of software design. UML has specialized diagrams dedicated for that. The problem with these diagrams is that they get outdated as soon as you start coding and the job of repeatedly fixing your diagrams to reflect what your code does means that this never happens and the diagrams get outdated very quickly.
Agile/extreme programming pretty much put a stop to writing documentation like this. These days few programmers even know what UML is and most have never encountered it professionally. I think that is a positive change. Build code, not stupid slide ware.
The reason for this is that this type of documentation is very maintenance heavy and only makes sense in waterfall style processes, which you should not be doing at this point. It got replaced by people drawing on whiteboards and maybe taking a photo of it. The value beyond the relevant sprint, or meeting, is usually very limited. They are great during meetings and their value drops rapidly after that meeting concludes. I've been in meetings where people take photos of whiteboards. In my view, even that is a waste of time. Just wipe it and move on.
A big problem is that state diagrams (and other diagrams) tend to abstract away too much information. A state diagram with around five states makes great slide-ware. But if your implementation has 25 states and dozens of arrows, that same slide basically becomes a mess and a PITA to update. So diagrams are great for things that are easy to explain without diagrams and not so great for more complicated things. In practice, if you can easily draw diagram, it's probably not worth bothering and if you can't you might consider writing a prototype instead.
Real systems tend to be more complicated than what you can fit in a diagram. Ultimately, it is the more complicated systems where people desire documentation; not the super simplistic systems where the documentation just states the bleedingly obvious. This is the reason UML died. It was used exclusively to document completely obvious things as part of rather pointless documentation that typically only told half the story. At great cost even.
I've seen and contributed to a fair bit of so-called architecture documents. This was a rather pointless artifact that used to be a box ticking exercise that involved a lot of tooling for drawing pretty pictures. Thankfully, it's been a while since I've been in a project where people asked for this. I used to refer to this as write only documentation because nobody actually reads this stuff. Project bureaucracy like this needs to be kept to a minimum.
I always joked that all the nice OSS UML tooling out there came without UML documentation. They did not eat their own dog food. None of them. UML documentation for OSS projects was never a thing. Even for OSS software intended to support writing UML diagrams.
I've found diagrams very useful for communicating with business/product teams, new devs, QA, and ops. Basically, anyone who isn't going to dive into the code where the State Machine is defined. Or if the Definition isn't laid out in one file or class. I'd rather use a text based language so I can include it in source control, so I use Dot: en.wikipedia.org/wiki/DOT_%28graph...
State machines and state machine diagrams aren't as popular in web development compared to other software industries. So personally, I haven't had the chance yet to use a state machine.
I've read up on them though and listened to a few podcasts. The most popular one that I've heard of is XState and I think there's a huge benefit to building more predictable UIs this way. I hope the concept and tools are more popularized in web development.
I like to use state machines a fair amount, and I always try to diagram them first. Nowadays I use stately.ai, as it's pretty comprehensive and easy to use. The docs are great too.