A developer I used to know put it thus: "A comment is an apology." I never asked him to explain that, but I guess he meant it's an apology that the code itself is not self-explanatory.
Clear, even verbose commentary can be helpful. But where it often breaks down is when the code is revisited, and the comments are not updated as well. So my practice now is to use comments in early development to help me remember what I was thinking in that bit of code, but then remove most of them during clean-up and refactoring unless something particularly non-obvious is going on. It makes future maintenance of the code less likely to diverge from the (usually unmaintained) comments.
Good code review could help here: "Hey, the diff shows you changed six lines of code in that function but the comments are the same, do they need to be revised?" But I've never worked anywhere where EVERY commit was reviewed, rather a sampling is selected for weekly review. that leaves a lot of opportunity for things to get missed.
Bottom line: extensive comments can add to workload when fixing bugs or making enhancements. So only use them when they really count.
The programmer who doesn't change the documentation when changing the code is usually the same one who doesn't change the function name when changing its functionality. If a bad programmer is tweaking your code, it doesn't really matter if the documentation is in the variable names or in the comments.
Meh, I'm a huge fan of "readable code" that is easy to follow and just makes sense with no need for explanations. And then there is code that is non trivial.
Too often I've found that vast amounts of effort were put into keeping something "readable" to the point that all of the extra readable hints either just got too large and unwieldy, or it prevented the developer from picking an easy and straight forward solution. (And to be fair, often that developer was me.)
I think there is a very real divide between what the logical flow for a computer to be presented something and the narrative flow for explaining that to another developer are. And no amount of clever variable/function names will really help here.
In fact, often times it can be worse. The proverbial isle of a grocery store. Too much to look at with no obvious "main" method. There is a reason it is a "rookie mistake" to have giant methods that do too much. When it comes down to it many people were only trying to get their program to do one thing. Cluttering their memory with the myriad steps necessary to get there is a large hurdle to get back into something.
Clear, even verbose commentary can be helpful. But where it often breaks down is when the code is revisited, and the comments are not updated as well. So my practice now is to use comments in early development to help me remember what I was thinking in that bit of code, but then remove most of them during clean-up and refactoring unless something particularly non-obvious is going on. It makes future maintenance of the code less likely to diverge from the (usually unmaintained) comments.
Good code review could help here: "Hey, the diff shows you changed six lines of code in that function but the comments are the same, do they need to be revised?" But I've never worked anywhere where EVERY commit was reviewed, rather a sampling is selected for weekly review. that leaves a lot of opportunity for things to get missed.
Bottom line: extensive comments can add to workload when fixing bugs or making enhancements. So only use them when they really count.