How Much Comment is Enough Comment

Adding comments has always been considered a boring and routine task, often done just for the sake of fulfilling a responsibility. This attitude also extends to writing non meaningful variable names. Writing code solely to get the expected output is, in essence, a selfish act.

I realized this when I read the comment section of a LeetCode discussion portal. There, a long, well-commented code was greatly appreciated, while a one-liner complex code with little to no comments was heavily criticized. From there i started to research How much comment is enough comment. A comment is essentially a bridge for understanding the coder's thought process. Understanding others is hard and depends on the level of empathy one has, which often develops through a capacity for helping others thus we should write a comment in such a manner that even a non coder could understand the code.

We can start by describing the approach or logic in multiple comment sections. Focus on adding only essential and relevant information, not unnecessary or overly interesting details. Write a brief story explaining the working of the code, so that the instructions (i.e., the code) can be easily understood by others. In single comment, give the reason of why that logic was implemented.

Use labels like TODO, FIXME, EXAMPLE, and NOTE to make the code more comprehensible and to convey your thoughts effectively.

• TODO: Use this for upcoming work or ideas that can be implemented in the future. This also help the developer to be within the scope of the story.
• FIXME: Use this for immediate fixes or hacks that were implemented to get the expected output but need enhancement.
• EXAMPLE: Use this to provide small demos explaining the logic of a function.
• documentation : add documentation and give it's URL link inside worklfow label.

For instance:

If comments are insufficient to convey your intentions, consider adding documentation. In documentation we can add the interesting stuffs which could hold the reader and feel the intention behind the code like what triggered this story or requirement or what all different approach were taken and blocker which forced to have this method. if even after that reader want to know more. Provide references or contact details so that others can reach out in case of any doubts.

In summary:

• Focus on essential and important information.
• Avoid adding interesting but relevant details.
• Use keyword like Example, TODO, FIXES, EXAMPLE.
• Use at least one multiple comment line to give the brief.

Lastly, check out the top 5 ways to make your code more readable to improve overall clarity.