Agreed. For example, comments about Why-do-this, and Why-Not-do-that can be necessary, even if the code shows what happens.
Imagine you're in a taxi, and it suddenly takes the wrong turn, now instead heading towards Surprise-City. Then — you know what is happening. You're going to Surprise-City.
But would't you also want to know Why?
So then it's nice if the taxi driver explains Why: "I buy milk to kitten."
I think the 'Linux kernel coding style' explains comments pretty well:
https://www.kernel.org/doc/html/v4.10/process/coding-style.h...
That's not necessary in every case. But it's true in a good number of them. The code alone can never tell you that - but it's often invaluable during evolution/refactoring.
What are you working around?
What are the assumptions? What limitations?
If it's complicated enough that I'm only understanding it because of the context of the last week, we need the comments. Anything that can speed the reverse engineering in 6 months when it breaks is helpful, because then you can quickly decide that we got different input or if we missed an edge case or whatever.
Someone updating the comments in code that they are updating because they see the comments right in front of them.
Or
Someone going to look through the documentation to see if there is anything relevant about the code they are working on that needs to be updated.
It takes 5 minutes to have thoughtful naming and "this is why because..."
They have done a stellar job at that.
I still believe this to be more or less true.
The important part there is that you have to write good code though.
Advice that relies on people caring about their craft/having the skills to do the work well doesn't scale, so it's bad advice where those things aren't true.
For example, instead of
if (order.version > 1) ...
assign it to a descriptive variable bool orderHasChanged = (order.version > 1);
if (orderHasChanged) ...
IMO this makes it much faster to read and understand, because it says something about the intent. It can also be easier to spot bugs.It's a bit more to write, but I find it makes a big difference when coming back to the code later on, and typing is usually not the limiting factor when writing code.
Time pressure (and particularly with contractors) can lead to some horrific long-term burdens of maintenance.
This is one of my biggest gripes. Someone (I think uncle bob) said that good code is self-documenting, which is bs in 95% of the cases. Yeah, you don't need to document the convertMinsToSecs() method, but most real life codebases are full with edge cases, shortcuts, temporary solutions, half-complete reorganizations. So people use this for writing no comments at all, whereas a few words of comments would save hours of investigative work for future developers working on the codebase.