I feel there is a huge over indexing on Clean Code and self describing code. Essentially are we suffering from a journeyman problem where the commentary we focus on are written by those that are new and have trouble understanding basic syntax? In that case the comments can be largely removed as describing a code statement with a comment indeed can often be replaced with a better statement.
Though, comments are so much more. They can be like the foreword in a book, the intro paragraph of a paper. While every paragraph might be easy to understand, a foreword to help the reader know what to expect can be invaluable.
Comments can be a scaling tool. A few lines above a test to tell me what is being tested might take 5s to digest, compared to adverse engineering the codd which might take 25s or longer. Multiplied over a dozen test cases, and you have something that can be understood in a minute compared to a dozen minutes. Multiply that put to a half dozen test suites or more and it is a time savings of hours.
As another analogy, it's like someone providing a travel itinerary. If you know the overall itinerary,the individual parts became expected and obvious - so much guess work of "where are we going with this" is removed. Instead that is replaced with, "I now expect these three steps", which makes it easier to recognize those steps and fit them into place.
Another analogy is a puzzle. Well written code is like having very large pieces where you can see a lot of detail. Good commentary is like having the full puzzle picture provided to you. Having both makes for an easy puzzle (which requires less time to understand, which means it requires less time to modify.)
Though, comments are so much more. They can be like the foreword in a book, the intro paragraph of a paper. While every paragraph might be easy to understand, a foreword to help the reader know what to expect can be invaluable.
Comments can be a scaling tool. A few lines above a test to tell me what is being tested might take 5s to digest, compared to adverse engineering the codd which might take 25s or longer. Multiplied over a dozen test cases, and you have something that can be understood in a minute compared to a dozen minutes. Multiply that put to a half dozen test suites or more and it is a time savings of hours.
As another analogy, it's like someone providing a travel itinerary. If you know the overall itinerary,the individual parts became expected and obvious - so much guess work of "where are we going with this" is removed. Instead that is replaced with, "I now expect these three steps", which makes it easier to recognize those steps and fit them into place.
Another analogy is a puzzle. Well written code is like having very large pieces where you can see a lot of detail. Good commentary is like having the full puzzle picture provided to you. Having both makes for an easy puzzle (which requires less time to understand, which means it requires less time to modify.)