Do the poka-yoke: building error proof software
The idea of building error proof software by leveraging the Japanese term "poka-yoke"
That's what it's all about
I consider myself fortunate as a Software Engineer with near zero hardware or electronics experience that I've had the privilege to lead a successful hardware project to market during my time as CTO of Australian energy startup Reposit Power.
That hardware is the RP400 electricity meter, an IoT device that is able to measure up to 6 loads/lines at an industry leading accuracy and speed, helping Reposit be the first in-market registered participant in critical grid stabilisation services.
While leading this project, I came across some interesting concepts in manufacturing that should be used more in software. One such idea is “poka-yoke” (pronounced roughly like poker-yokeh).
In 2019, I was on the floor of the factory in Adelaide that was manufacturing our PCBs and working through the process of assembly. It's a big factory with a lot of automation for building high end parts for cars such as McLarens, and has a clean room for PCB manufacturing. It's quiet and desolate these days - just the left overs of what once was a bustling car manufacturing industry here in Australia.
A poka-what, now?
During assembly the software is installed to each device by inserting an SD card and powering on the device. As we were walking through the software install process I highlighted the importance of removing the SD card before putting on the enclosure. The two technicians from the manufacturer quickly turned to each other and said “we’ll need a poka-yoke for that”. I replied “a what?!?!”.
Poka-yoke is a Japanese term that means "mistake-proofing" or "error prevention". A poka-yoke is any mechanism in a process that helps an equipment operator avoid (yokeru) mistakes (poka) and defects by preventing, correcting, or drawing attention to human errors as they occur.
Manufacturing and software engineering often takes inspiration from Japanese culture with many techniques and processes - such as lean manufacturing and “Kaizen” - popularised by Toyota in Japan.
“Poka-yoke” isn’t a Japanese term I'd previously come across though.
At first glance it might seem like a simple step in the assembly instructions would suffice - “remove the SD card”. But poka-yoke is more than that, it's about making the mistake impossible in the first place.
It could be designing the enclosure such that it can’t be closed if the SD card is still inserted. This means poka-yoke can't be an after thought - it needs to be right there in the design itself.
Or it could be as simple as super-glueing some twine to the SD card and the technicians desk so that the device can't be packed if it's still physically attached to the desk.
A wild poka-yoke appeared!
I came across a really great example of a poka-yoke recently in a Roborock vacuum. There is a little sprung piece that goes under the removable filter in the dustbin. If the filter is removed the piece rotates up and blocks the dustbin lid from closing, and therefore being unable to be inserted in the vacuum. It makes it impossible to insert the dustbin without the filter. Very simple, but a great design.
Check out the video below to see how it works.
If you look hard enough, you see poka-yoke design everywhere. There’s something you use almost every day - a simple Australian plug has a design that makes it impossible to accidentally insert it backwards and swap live and neutral by mistake.
Poka-yoke in software
I like to think of poka-yoke in software engineering - often times it enters my mind when there has been a bug discovered or a production incident. Finding the issue and fixing the issue is great, but how do you make it impossible for it to occur again?
As teams grow and as software grows in complexity it's easy for an innocent change to forget about a previous fix and reintroduce that bug via a different edge case. Maybe we were good and added unit tests when we fixed the bug. Maybe we didn't.
I always say that having a bug occur is OK, having the same bug reoccur multiple times is not, but I've seen it happen. There was no poka-yoke.
It's not just bugs though, it could be user input or actions, a series of events that we didn't expect to happen but was permissible to the user and it puts the data in a weird unexpected state. What's the poka-yoke for that?
I think a simple and common example is boolean flags, in my opinion they are over used and error prone, and don't contain a natural poka-yoke.
Consider modelling the state of a plane. We could have two booleans flags:
engines_running: true/false
in_air: true/false
We can then determine if the plane is taxiing, flying or stopped as a combination of these:
taxiing = engines_running: true AND in_air: false
flying = engines_running: true AND in_air: true
stopped = engines_running: false AND in_air: false
But that leaves a state we haven't catered for:
engines_running: false AND in_air: true
What's does that mean for our plane? Is it gliding? Engine failure? Either way we haven’t catered for it and our program is likely to crash.
A poka-yoke for this could simply be to make it an enumeration:
plane_status: taxiing | flying | stopped
Most languages will let you define this as some sort of enum type and it will be statically checked at compile time (or during dev with a good IDE). If you try to assign an unexpected value, your program won’t compile or pass CI/CD checks.
You now have a poka-yoke. It's impossible to assign an unexpected state.
Will you do the poka-yoke?
Next time you’re writing software or squashing bugs, say to yourself “what's the poka-yoke for this?”. Say it to your team mates and peers when working through problems “that's a good fix, but what's the poka-yoke for it?”. Make it a term you can throw around to hold yourselves accountable to achieve good engineering.
I'd love to know if you've come across any poka-yokes in the wild or implemented any yourself. If you have let me know in the comments!
Thanks for sharing Mike. A great explanation of a process I had not heard of before but felt similar to Bertrand Meyer's Design by Contract in Software Engineering where our software is equiped with pre-conditions, post-conditions and invariants. They also go a long way to documenting what our software does.
Design by Contract in software engineering aligns with the Poka-Yoke design concept by emphasising clear specifications, error prevention at the source, contract violation detection, and proactive design to enhance the reliability and robustness of software components and systems. Both approaches share the goal of reducing errors and defects by addressing them early in the development or operational process.