Good code comments explain why, not what. The code itself already shows what it does, so a comment earns its place by capturing intent, reasoning, or context that the code cannot express, like why you chose an unusual approach or what edge case forced a workaround. The best habit is to write clear code that needs few comments, then add notes only where the why is not obvious. In 2026, with AI tools generating and reading code constantly, comments that record human intent matter more than ever.
Why comments exist at all
Code tells the machine what to do. Comments tell the next human, often your future self, why it does it that way. A line that looks strange might be a deliberate fix for a tricky bug, and without a note explaining that, someone will eventually "clean it up" and reintroduce the problem.
That is the core principle: comments should add information the code cannot convey on its own. If a comment merely repeats what the code already says, it is noise that will rot the moment the code changes.
-- Weak comment: just repeats the code
total = total + 1 -- add one to total
-- Useful comment: explains the why
total = total + 1 -- retries are counted separately per the API rate-limit rules
Good comments versus bad comments
| Comment type |
Example purpose |
Keep it? |
| Why a decision was made |
Explaining an unusual approach |
Yes |
| Edge cases and workarounds |
Noting a fix for a known bug |
Yes |
| Public function documentation |
Describing inputs and outputs |
Yes |
| Restating obvious code |
Narrating a simple loop |
No |
| Outdated notes |
Describing removed behavior |
Delete |
| Commented-out code |
Old code left behind |
Delete, use version control |
When in doubt, ask whether a reader who knows the language would learn something from the comment. If not, it probably should not exist.
How to comment well
- Write the code clearly first. Good names and small functions remove the need for most comments before you write any.
- Comment the why. Capture intent, trade-offs, and the reasons behind non-obvious choices.
- Flag the surprising parts. Workarounds, edge cases, and anything that would make a reader pause deserve a note.
- Document public interfaces. Functions others call benefit from a short description of what they do and expect.
- Update comments with the code. Treat a stale comment as a bug, because a wrong comment is worse than none.
- Delete dead notes and code. Version control remembers old code, so do not leave it commented out.
Cleaner code naturally needs fewer comments, so reinforce this with how to write better code, and pair it with how to name variables to reduce the need for explanation in the first place.
Common mistakes
- Narrating obvious lines. Comments that restate simple code add clutter and hide the comments that matter.
- Letting comments go stale. Code changes but the comment does not, and now it actively misleads readers.
- Leaving commented-out code. It confuses readers and your version control already keeps the history safely.
- Over-commenting to look thorough. Volume is not value; a few precise notes beat a wall of narration.
What to skip
- Skip commenting self-explanatory code. If a clear name already says it, a comment just repeats and ages poorly.
- Skip apologizing in comments. Notes like rough or fix later without context help no one; either fix it or explain the plan.
FAQ
Should I comment every function?
No. Document public functions others rely on, but private helpers with clear names often need no comment at all.
Is it bad to have too many comments?
It can be. Excessive comments hide the important ones and tend to go stale. Aim for clear code with a few meaningful notes.
What is the difference between why and what comments?
A what comment restates the code and adds little. A why comment explains intent or reasoning the code cannot show, which is what makes it valuable.
Do AI coding tools change how I comment?
They raise the value of intent. AI can read code, but comments that record why a human made a decision still guide both people and tools.
Where to go next
How to write better code in 2026, How to name variables in 2026, and How to write a function in 2026.