In most codebases, there is more legacy code in comments rather than actual comments. While coding we often come across the question of why, where and how to write comments. In most scenarios, we either end up adding unnecessary comments or miss adding any required comments. In this article, we will try and explore the different aspects of comments which will help us in judging & writing productive comments in our code base.

A General disclaimer Comments are the essence of a good program, i.e. it complement the code but does not cover up any bad coding practice. It's the same difference between eating from a food truck & dining in a fancy restaurant. In either of the cases, if the food is not good, it won't sustain. Similarly, if the code is not good enough no comments can be of any help.

Why add comments

Code has two audiences, one is the compiler which interprets it into machine language and the other is humans. Thus, to enhance our readability adding comments is key. It not only helps our peers to understand the code but also helps us to recall any old piece of code authored by us. Within a team, it creates a sense of understanding and encourages effective collaboration. Comments also act as reference notes for the reader to share details or reference links. During PR reviews it becomes easier for the reviewer to understand the underlying logic and resolve conflicts. It also attracts useful suggestions from peers on which to improve. Especially, while working on open-source projects the comments advocate for the code as we directly do not connect with the reviewer. It helps to understand the reviewer from the coder's point of view.

Where to add a comment Most of the developers are unaware of where to add a comment. Adding too much of a comment can backfire and diminish the code readability and reusability. The comments require to be added scientifically which can complement the code. Comments in block

Add comments in a block at the top of the source code file. Limit it to 2-3 lines only explaining the use of that particular class/method/abstract etc. If any particular code is referred it's always best practice to mention the link of that source code here. TODO comments

As the name refers, these comments act as a bookmark within the code base to remind the developers of any pending actions required to be scripted. These should be written in short phrases mostly. Inline comments

Developers often tend to write numerous inline comments which is unnecessary and makes the code clumsy. These should be avoided unless there is a tech debt which requires explanation. In the above dart code, we have multiple parentheses opening and closing sequentially. Adding just the name of the block to these parentheses closing, makes it easier for developers to understand and refactor them correctly.

Adding good comments is an unspoken expectation from any developer. There is no hard rule for commenting but it's a good habit to add meaningful comments and maintain them. It improves readability and encourages positive conversation among peers for better coding solutions.