Few days back I was going through some of my old code for a personal project of mine and the difficulty I faced trying to understand my own code motivated me to write this article. All because I didn’t care to add comments. Similar to my previous article, this too is for the beginners. To guide and help them learn from my mistakes.
So, why are comments so important in coding? As a beginner, especially when we start writing some basic code we are told to comment out code properly. But we, in our excitement to see our code running and the output being displayed on the screen don’t really pay heed to it. We code, make sure the output is correct, and move on to the next one. This slowly becomes a habit and even in professional situations we forget to comment out code. What happens then is that when we need to go back to look at a piece of code which we wrote even just a few months back we end up wasting hours just trying to make sense of what we did and why we did. Trust me it happens.
Similarly, if we get a code from another developer which does not have comments or has badly written code comments, we have to waste precious hours (hours which can be better utilized actually writing code) just making heads or tails of the code. Now, you don't want this to happen with you and further, you don't want your code to cause the same to someone else. Hence, the need to start adding code comments.
Another way to look at this is, imagine working with a team of developers. You need to connect and coordinate to render the output. Not commenting would mean spending hours to understand what the program does and how. This adds to the time taken to build the project, costing both in terms of money and effort.
Hope that makes sense. Let me try putting it in a different way. Here are a few ways commenting your code helps:
It makes immediate sense to other coders reading it: When working with a team of developers or an open source project with several contributors you want to make sure that your code makes sense to others working alongside you. This is where code comments come into the picture. Not only do good code comments explain what you are trying to achieve, but also reduce the chances of bugs and errors caused by misunderstanding between two developers working on common code.
It makes sense to you when you come back after a while: Whether you are working in a professional setting or otherwise, more often than not, situations will arise where you will have to revisit old code. It may be for fixing a client issue or making an enhancement or simply to reuse the already-written code for your new project. Whatever be the case, good code comments make sure you don’t have to struggle to remember what you wrote and why it was done in that way. You might think, ”Oh, it’s my code I will remember” but you won’t. If you add good code comments while writing the code you need not go through this frustrating scenario.
Helps you in structuring your code better: When you have read code from different developers for a long time, you will feel some of the code is just so elegant and free flowing that the next step feels obvious. Code comments help in writing such clean code. Writing code comments along with your code helps you think in a certain way. Sort of like steps in a recipe. This helps you structure your code better and overall flow of the code improves.
Experimenting with your code: Sometimes while tackling a problem you might come up with multiple solutions for the same or while learning you might want to try the same problem in a different manner. Code comments can help you here as well. Instead of deleting the working code or starting in an entirely new file, simply comment out the part you want to implement differently and experiment away. This makes sure you don’t break anything while trying something new.
Documentation generation: Most of you might not know this but code comments are a superb way for generating software documentation(user guides/manuals). If you have good code comments within your code, the documentation step becomes a lot easier. It further reduces the time and effort required, making the software ready to ship.
Most of the time coding is a community exercise involving more than one person usually. The habit of commenting makes sure your code is more readable and well structured making life easier for you and your peers in the long run.
There’s the other side of the coin as well. Too many comments. You don’t want a program of 30 lines to have 40 lines of comments. You don’t have to comment on each and every line of code. Parts of code which are self-explanatory don't require code comments. For example, a print statement doesn’t need a comment saying “This line prints something”. Don’t write vague comments. They just complicate things.
Remember, code comments should be at places where they are necessary for the code to make sense to a completely new reader. Comments should be a helping hand not a burden.
So, the question that comes here is, how exactly do we decide where to comment and where to not?
The Golden Rule for Commenting Code
As a general rule of thumb, you can put comments in places where you are using a specific approach to solve a problem which otherwise might not be apparent to someone else. Basically, the idea is to state why you did what you did. One line explanations for code blocks like functions. Places where the flow of your code changes.
As you can see it is very important to add comments to your code. Badly commented code is as bad as not commented code if not more. Hence, it is important to build a habit of commenting code from the start.
That was it from my side on the importance of commenting. Follow this blog to stay updated. If there is any specific topic you want me to write on, do let me know in the comments. Till then, Keep coding, Keep learning, Cheers !!!
Top comments (0)