"I used to write comments like this:
// increment i by 1
i++;
Thank you, Captain Obvious.
Then I stopped writing comments altogether. And then I realised: comments are not for explaining what the code does. They‘re for explaining why."
1. The Problem With Obvious Comments
Most comments are useless. They repeat what the code already says.
// set x to 5 before x = 5; — that‘s not helpful. That‘s noise.
Good comments don‘t explain what — they explain why.
2. Comments Are for Your Future Self
You write code today and understand it perfectly. Then you come back in 6 months and think: 'What was I thinking?'
A good comment is a message to your future self: 'I know this looks weird. Here‘s why I did it this way.'
3. Comments Are for Your Teammates
When you work in a team, your code is read by others. A good comment can save someone hours of confusion.
It‘s not about being nice. It‘s about being professional.
4. The Best Comments Are Short
A good comment is 1–2 lines. It doesn‘t explain the whole function — just the tricky part.
If you need 10 lines to explain your code, maybe the code is the problem.
5. When NOT to Write Comments
Don‘t comment:
- Obvious things (i++)
- Things that change often (comments get outdated)
- Bad code (fix the code, don‘t explain it)
Code should be self-explanatory. Comments are for the exceptions.
6. The Types of Comments I Actually Use
Here‘s what I write:
- Why: 'We use this workaround because the API is broken'*
- Warning: 'Do not change this — it will break the login flow'*
- TODO: 'Refactor this after the release'*
Everything else is noise.
7. The Sad Truth
Most comments are never read. Most code is never read. We write it, we ship it, and we move on.
But the comments that matter — the ones that explain why — those are the ones that save lives (or at least, save hours).
"Code tells you how. Comments tell you why.
And in a world where everything changes fast, 'why' is the only thing that stays valuable."
What About You?
"Do you write comments? Or do you think they‘re a waste of time?
Let me know in the comments — I‘d love to hear your perspective."
"If this article made you smile or think, leave a tip or a like — it keeps me writing honest content."
#comments, #cleancode, #programming, #softwareengineering
