Is Commenting Good in Code? — The Real Deal About Code Comments

When writing code, one question often pops up: “Should I write comments or not?” Comments are those little notes we leave inside code to explain what’s going on. But are they really good? Or can they cause more harm than good? Let’s dive into the world of code comments and figure it out.

Why Do We Write Comments?

Comments are meant to:

• Explain why something is done a certain way.
• Clarify complex logic that might not be obvious.
• Provide context that the code alone doesn’t tell.
• Help future you or other developers understand the code faster.

For example:

# Calculate the total price after discount
total_price = price * (1 - discount_rate)

Here, the comment explains the purpose of the calculation.

The Pros of Commenting

1. Improves Readability
   Comments can make it easier for others (or yourself in the future) to understand your thought process.

2. Speeds Up Onboarding
   New team members can get up to speed quicker with helpful explanations.

3. Documents Assumptions and Intent
   Sometimes code shows how but not why. Comments fill that gap.

4. Helps Debugging
   When debugging, comments can guide you to the important parts or assumptions in the code.

The Cons of Commenting

1. Comments Can Become Outdated
   If you change the code but forget to update the comments, they become misleading — worse than no comments.

2. Over-Commenting Clutters Code
   Too many comments can make code messy and harder to scan quickly.

3. Comments Can Hide Bad Code
   Sometimes, developers use comments to explain complicated code that should actually be simplified.

4. Lazy Developers Rely on Comments
   Instead of writing clear code, they write messy code and add comments to explain it — which isn’t ideal.

When Should You Comment?

• When the why is not obvious.
• To explain complex algorithms or logic.
• To note important assumptions or side effects.
• To warn about potential pitfalls or temporary hacks.
• To mark TODOs or future improvements.

When Should You Avoid Comments?

• Avoid stating the obvious, like:

i = 0  # Set i to zero

• Avoid repeating what the code says.
• Avoid writing comments that will likely be forgotten to update.

The Best Alternative to Comments: Write Clear Code

The best way to reduce the need for comments is to write clean, readable, and self-explanatory code:

• Use meaningful variable and function names.
• Break down complex code into small, reusable functions.
• Use consistent coding style and formatting.
• Avoid deep nesting and long functions.

If your code is easy to read, you need fewer comments.

Final Thoughts

Comments are good when they help explain why something is done or clarify complex parts. But they are bad if they are outdated, redundant, or used to justify unclear code.

Use comments wisely — as a tool to complement clean code, not as a crutch to fix messy code.