A week ago, I was working on a coding task. That was not difficult at all. If you are a little bit into programming, it’s the kind of task in which you have to handle a lot of different cases. The operations were relatively easy in each case. The main problem was trying to deal with all those cases all at once.
In other words, that was nothing special.
As there were no challenging algorithms to deal with, I was in the mindset of building the perfect code on the first shot. It was not my intention to go through a series of trial and error and only add a few comments in the end. My drive was the development of a flawless script right from the start.
Code documentation is also a part of this.
Contrary to what I usually do, I continuously commented on my code as I was building it. Everything was going okay until I hit a problem with one of the libraries I had previously built.
Let me clarify: this was not a bug I found through testing. I realized there were some issues because of a mental process that started with my writing. Commenting enabled me to visualize the execution flow more clearly. Such practice led me to spot existing issues.
What’s the conclusion, then?
Without the practice of commenting, I would have never discovered the flaw with my previous work. I would have inevitably tested my code in the end. When I detected the problems, I would have first searched for the last piece I had built.
In the end, I would probably have found the mistake anyway, but at the cost of spending a lot more time dealing with it.
Online resources show many reasons why commenting on your code is beneficial. Among all the reasons you often find is clarity. It makes the code easier to understand, either for your future self or for others. For instance, when you’re working on a project with a team, explicit comments can help your colleagues understand your code faster.
I’d like to add that this clarity also happens in your mind. When you write down what you are doing, everything looks more transparent.
This way, you will be able to spot a lot of problems before starting your tests. You can save a lot of time doing so. And even if you don’t spot any errors, you have a good code for others to understand.
In conclusion, commenting is a crucial practice that can save you hours of debugging and ensure the reliability of your work. Start commenting mindfully from the start of your next project and observe the difference it makes.