📖 Business
Biz - Comments Are a Failure
Martin's provocative but principled argument: most comments exist because the code failed to explain itself. Comments are not inherently bad, but they are a last resort — a sign that the developer could not find a way to express intent through code alone. The deeper problem is that comments lie. Code changes, but comments don't get updated. Over time, misleading comments become more dangerous than no comments at all, because readers trust them and act on outdated information.
2
Minutes
2
Concepts
+45
XP
1
How It Works
Good comments (the exceptions that prove the rule):
- Legal/copyright notices — required, not explanatory.
- Explanation of intent — why a non-obvious decision was made ("We use insertion sort here because the data is nearly sorted and n < 50").
- Clarification of obscure library behavior — when you're calling an API that behaves counterintuitively, a comment explaining the quirk saves the next person hours.
- TODO markers — flags for known incomplete work, searchable and trackable.
- Warning of consequences — "This test takes 30 minutes to run" or "Do not change this order without updating the migration."
Bad comments (the majority):
- Redundant comments that restate the code:
// increment iabovei++. Adds noise, no signal. - Mandated Javadoc/JSDoc on every method — most of these are templated noise that no one reads.
- Commented-out code — version control exists for exactly this purpose. Delete it.
- Position markers —
////// SECTION //////or// ---------- Helpers ----------. If you need section markers, the file is too long. - Attribution comments — "Added by Matt on 3/15." That's what
git blameis for. - Journal comments — changelogs at the top of the file. That's what commit history is for.
The fix: when you feel the urge to write a comment, first try to make the code clearer. Extract a well-named function. Rename a variable. Restructure the logic. If you still need a comment after doing all of that, write it — but make it explain why, not what.