I think the "good code doesn't need comments" argument is often aimed at the wrong target.
Well-written code shouldn't need comments explaining what it does:
# Increment counter by one
counter += 1
That's just duplication.
But comments aren't only for explaining mechanics. They're often the only place we can capture intent.
Code can tell me how something works. It usually can't tell me:
- Why a business rule exists
- Why an apparently strange implementation was chosen
- Which production incident is this code preventing from recurring
- What external requirement or regulation drove the decision
- Which assumptions future maintainers should not casually remove
Years into my career now, the comments I've appreciated most weren't explanations of syntax. They were breadcrumbs left by a previous developer, explaining the problem they were trying to solve and what would break if I "cleaned up" their code.
Future me has thanked past me for good comments far more often than for clever code.
Back in the COBOL/mainframe era, comments were often treated as documentation because the people maintaining the system years later might not even be the same company, let alone the same team. Then the Clean Code movement correctly pushed back against comments that merely translated code into English.
The pendulum swung from:
"Comment everything."
to
"Comment nothing."
The healthier position is:
"Comment decisions, assumptions, constraints, and intent. Let the code explain mechanics."
That's a rule that's held up pretty well across every codebase I've touched.
