Sometimes I read articles about the importance of commenting your code properly. If you work in the tech, you probably know the helpful comments on
updateState() method that say
updates the state. But I want to make this article generally applicable, so read on.
Commenting your code is really a different way of saying that you’re documenting your progress. When you open the same code next time, be it tomorrow or after one year, you should quickly grasp from the comments you wrote (or somebody else) what the given piece of code does.
The same principle is applicable elsewhere. If you work in marketing and you are going through the list of your leads, you should be able to come in later and be able to pick up the work where you left it. That’s the whole purpose of documenting your work.
To contrast, let’s see what happens when you don’t document your process properly. If you’ve called any customer support recently, how many times did you have to say the same information to the person on the other end? Perhaps one agent is writing down notes about you and thus “commenting their progress,” but it’s all useless when the next agent cannot read these notes and has to start all over.
I will use another anecdote why it’s important to comment your progress properly. I was recently in the hospital and I managed to sneak inside while the previous patient was being served. The doctor was looking at her CT scan and then asked her a question about her health problem. All fine, except this health problem first occurred 14 years ago. Understandably, the patient didn’t remember the details to be able to answer the question.
All this could’ve been prevented if the doctor who made the scan 14 years ago wrote a simple note why they performed the check up on her back then. While they probably saved a few seconds back then, now the patient might get an incorrect treatment.
Whenever you do something at least remotely important, make sure you document your progress. You never know, it might save someone’s life.