Of course it is easier if comments explain the code.
But what if comments and code become desynchronised?
How about some self-explaining code instructions?
That is the purpose of don't use comments: functions names, variables names, code organization that self-explain its intention.
I agree with intent-commenting, but I can answer your other two concerns...
But what if comments and code become desynchronised?
Then fix both. My team has used intent-commenting as a mandatory part of the code base for years, and desync nearly always indicates a logic bug. You'll note no one makes this complaint about function names, even though those are just as likely to fall out of sync. They fix the name.
How about some self-explaining code instructions?
Code should always self-explain what it does, but it is virtually impossible for code to explain its own code-agnostic intent.
Of course it is easier if comments explain the code.
But what if comments and code become desynchronised?
How about some self-explaining code instructions?
That is the purpose of don't use comments: functions names, variables names, code organization that self-explain its intention.
I agree with intent-commenting, but I can answer your other two concerns...
Then fix both. My team has used intent-commenting as a mandatory part of the code base for years, and desync nearly always indicates a logic bug. You'll note no one makes this complaint about function names, even though those are just as likely to fall out of sync. They fix the name.
Code should always self-explain what it does, but it is virtually impossible for code to explain its own code-agnostic intent.
To Comment Or Not To Comment?
Jason C. McDonald ・ Jan 20 ・ 12 min read