Don't use comments. Instead try to name your functions and variables > better. Comments are allowed only for TODO, FIXME (not on master branch > though) and some special cases where you would want to describe your > intentions instead of mechanism.
I don't agree with this. The only case where comments aren't useful are autogenerated comments by IDE's (Java I'm looking at you).
It makes it easier and quicker to understand the source code, Especially in open source projects with a lot of contributors.
I've found that it's easier for me to understand the code if they're helpful comments about what a particular block of code/function does. I can just skip the code if the comment says it does something different that I'm not interested in. I don't need to read it.
On the other hand, if there's no comment (and you have just "special" comments) you'll spend a lot of time reading a lot of code that has nothing to do with what you're interested in at that moment No matter how clear the function/method name is.
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.
I don't agree with this. The only case where comments aren't useful are autogenerated comments by IDE's (Java I'm looking at you).
It makes it easier and quicker to understand the source code, Especially in open source projects with a lot of contributors.
I've found that it's easier for me to understand the code if they're helpful comments about what a particular block of code/function does. I can just skip the code if the comment says it does something different that I'm not interested in. I don't need to read it.
On the other hand, if there's no comment (and you have just "special" comments) you'll spend a lot of time reading a lot of code that has nothing to do with what you're interested in at that moment No matter how clear the function/method name is.
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