I learned my first lesson of why a 'Lock out Tag Out' procedure is so very important at my recycling job assisting maintenance with our Balemaster 2000.
This machine baled cardboard, metal, almost anything. A giant metal head sitting at the bottom of a 40ft tall shoot would press forward with the power of a hydraulic line bigger than an adult human leg. It used 40,000 Watts to power motors, fans and a giant conveyor belt that could hold and move tons of weight at a steady pace.
This is not a complicated machine, but deadly under terrible circumstances, as I learned that day.
We were getting ready to change a fuse, one of the two that were linked to the 40,000 watts. The maintenance man was in a hurry, because the baler being down meant profits were being lost by the minute. As I stood next to him, he reached in to grab the first fuse ... The machines power button was in off position, but the power supply was not.
He luckily just received a jolt, and me a big static charge. But it was that day he taught me all about locking out power supplies, and why it's important, because he had forgotten and it could have been deadly for both of us.
We proceeded to pull down the breaker on the main power box, and on the machine and lock them out with padlocks. The keys to these locks he kept in his pocket. No one could remove the locks without that key, or bolt cutters. The power supply was confidently off. We could finish replacing the fuses now. Although I think we both flinched regardless when he reached for the fuses this time.
A lock signifies something is off limits. It's pretty universal, so we could be confident that anyone seeing the lock on the breaker box, or on the machine, would not simply 'take it off' without some kind of confirmation it was ok to do so. The tag on the lock stated what was going on, 'repair of baler in progress'. People were working on that machine. A tag dangled from each of the locks, big red bold letters, a warning label with written description of what was going on. This was not just locked for no reason.
At the paper mill this process was massive when the paper machine had to be shut down for repairs. Our locks even had our names on them. Every person working on that machine had a padlock on the master box, which had all keys to all systems locked inside it. Until everyone had confirmed their duties were complete and they were no longer in the path of the machine or it's systems, the machine could NOT be turned on.
Clear and precise communication that can not be misunderstood is important, it's not always easy, and is useful to all who encounter it.
Commenting your code:
It may not be life threatening, it may not seem like a big deal that someone knows and understands the intentions of a piece of code. There are some that will say 'well written code requires no explanation'. It's the same with lock out tag out procedures, except we deliberately put the items, tags, paperwork in place so that there is a miniscule possibility a machine's power is turned back on before it is safe to do so.
Even if your code could be read and written by the newest of coders, the intent, the purpose and the use of a piece of code should be absolutely clear. Maybe it is as simple as:
"An add function that sums two variables x and y."
But wait... are those variables integers? are they strings? are they floats?
revised: "An add function that sums up two integers x and y."
But wait... where are x and y coming from?
revised: "The add(x, y) function whose purpose is to add integer parameters x and y."
revised: "The add(x, y) function whose purpose is to add integer parameters x and y returns a whole number, rounded up with python import math and round() methods."
Now that's a bit closer to being a LOTO(lock out tag out).
I'll admit, I may not go that in depth with a comment, but there is absolutely no harm done by doing so, and only serves to safe guard anyone who uses your code in the future.
Now lets take a bigger example. At one time I was trying out a python module called timeit(). I was running a python random function to produce a huge self coded list of double linked list nodes.
The times on my timeit were huge, slowing and almost crashing my computer. It was running hot and hard trying to do this process that I thought should be small and easy. I was calling timeit on my double linked list, just too see how fast it could run from start node, to end node.
What I didn't find in the documentation at the time was that timeit had a default, if you didn't specify how many times for it to run the test, it tried to run the test 1 million times. Me being a newbie, assumed it only ran one test when you used it, unless you told it to run more. I was building a 800 node doubly linked list 1 million times. I found out later, through some googling and digging about the default.
Again, not life threatening, it didn't kill my computer but it sure did cause me some grief and aggravation trying to find out what was happening. Not a comment per say, but definitely an item that should have been clearly and specifically stated in the documentation.
Lets make a bigger example.
I don't know how feasible it is that things like this happen, but I know mistakes happen in every industry, everywhere.
A piece of code is in a required system that runs the hospitals emergency generators. The power fails. Someone is called in to look at this code, and it is written so that only the person who originally designed the system understands what part of the systems it controls, and what part of the power supply it's connected to. There are no comments. Time matters, it matters how fast and how easily someone can fix and repair this situation. Maybe the tech squad sent in is completely brilliant and reads the code without issue. Maybe they can't. Maybe this old code was supposed to be removed a long time ago, but somehow it never made it on the list for an update.
Put your lock out tag out on your code. It may just be a matter of saving someone a little grief, it may save someone's precious time. It may keep a system accessible and fixable for years.
It may never matter, but why take the chance? Why not add a little safety to your code, leave it behind for others to easily engage with and understand. Practicing this step will keep you from leaving it out when it may really matter.
Level up every day