I think most people would be blown away once they see how heavily complex codebases are commented.
I don’t buy into “Your code should be self explanatory” and the reasoning for that is once we start adding business insights into codebase, it loses half its meaning.
The code can’t talk back to us and tell why certain things are behaving in certain way. No matter how “clean” we keep it. We can’t always add meaning to it.
So for me, “WHY” something was done in certain way is absolutely critical before I can add any new features or refactor it.
I know “WHAT” I need to do if requirements are clear but from what I’ve seen most codebases rarely answers “WHY” unless someone has been kind enough to leave comments.
What I’ve also seen is as the code becomes more and more complex, the developers who maintain it tend to add as many comment as possible, not for future developers but for themselves (tests are not a replacement for comments, sorry!).
I guess it goes to show that even people who regularly maintain it need additional comments to make sense of their own code as the complexity grows.
I don’t think a function, class name, variable, how things are connected can ever give you a full picture.
For context I’m working on an invoice management software and there’s no way it would’ve continued making sense without meaningful comments.
Even though the “code” itself is quite clean the insights/comments and tests have become essential for proper development.
Maybe this problem is specific to certain type of software!
