If you want to learn code, you have lots of resources. You can read books, or watch tutorials on YouTube or other platforms. No shortage of resources. But there are very few resources about best practices for writing code comments. It’s hard to measure the quality of good comments. A bad comment is worse than no comment at all.
Now you might ask me, why comments? It’s no matter if I add a comment or not. The program works fine.
You are right, your comment will not execute on the program but most of the time, not one person working on a project. That means other people might need to read your code and have to understand it. So it’s important to have comments.
There are three main reasons for writing comments in your code:
Here are some tips to write good comments.
I always write comments while I write code, because most of the time, I forget why I wrote this, Sometimes I feel so lazy to add comments later. so for me, it’s best practice to write comments while writing code.
Sometimes you will find some code, that solves a problem in a very complex way. Instead of this way they have an easy way. And the comment is very unclear, in most cases, it’s because the programmer does not understand the problem properly. This type of comment not only spoil time for other developer but also for the developer who worked on the project. So your comment should be straightforward.
Remember!! Your comment should not create confusion, your comment should disappear confusion.
When you add a new feature or build a logic always add a comment, about why you are doing this. It will help you to understand this later. Most of the time developer forgets, why they added this. You need to read code, sometimes multiple times to understand why you have written this code. So good commenting can save your time.
It’s very important to add comments when you want to fix any bugs or want to include a new feature. Sometimes after fixing a problem, it generates a big issue on the site of a program. In that case, your comment will be a lifesaver. Also, it will be easy to determine, where is the problem.
If you think you need to add a document to clarify a code’s purpose, it’s a red flag for bad code. You don’t want to spend time searching for other code comments or reading extensive design documents.
I hope this video helped you a lot to understand why a good comment is important. As Stack Overflow co-founder Jeff Atwood has written, “Code Tells You How. Comments Tell You Why”. If you are able to write good code it can save your time as well as your teammate’s time and frustration.
What do you think about this blog post, let me know in the comment. Thank you for your time. Have a nice day..