The Case Against NOT Commenting
Programmer's Hubris Leads to 6-Month Delay as Team Attempts to Understand 'Obvious' Algorithm
Dear Marilyn: I understand my code perfectly. Why should I waste time writing comments for myself?
— Confident Coder in Chicago
Dear Confident: Do you also remember what you had for lunch three Tuesdays ago? The human brain has a remarkable capacity for forgetting things it once knew intimately. In six months, your "perfectly clear" code will look like ancient hieroglyphics—and you'll be the archaeologist trying to decode your own tomb.
The Three Excuses (And Why They're Wrong)
"Good code is self-documenting"
Good code tells you WHAT it does. Comments tell you WHY it does it. These are different questions. A well-named function calledcalculateTaxWithSpecialRules() tells you what happens, but not why those special rules exist or what business requirement demanded them.
"Comments get out of sync with code"
This is like saying "I don't maintain my car because maintenance is hard." Yes, comments require maintenance. So does everything else worth having. The solution is to update comments when you update code, not to abandon them entirely.
"I'll remember what this does"
No, you won't. And even if you do, your colleagues won't. And your replacement definitely won't. Code is written once but read hundreds of times. Optimize for the readers, not the writer.
The Real Cost of Not Commenting
Quick Check
What is the main difference between what code tells you and what comments tell you?