Best practice for writing code comments

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.

Remember !! Good code is self-documenting and professional programming means commenting.

Why comments are Crucial

There are three main reasons for writing comments in your code:

• Communication
• Clarity
• Explanation

Most of the time we use three types of code comments and they are

• Documentation comments. It quickly clarifies the purpose why this code.
• Function comments. It explains the function well
• Logic comments. It explains the logic of clarifying complex code paths.

Here are some tips to write good comments.

Tips 01: Write comments while Writing code

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.

Tips 02: Write short yet informative comments.

A famous quote: If you can’t write a clear comment, there may be a problem with the 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.

Tips 03: Write down why you are doing something

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.

Tips 04: Add comments when fixing bugs

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.

Tips 05: Don’t refer to other documents or comments

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.

Sometimes you might need to add header comments and sometimes you need to use single-line comments. Use these two comment types wisely.

Do not write a useless comment or comment that does not add or generate any value. Ignore this type of comment.

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..