Unfortunately the comments that could be generated are exactly the ones that should never be written. You want the comment to explain why, the information missing from the code.
This is something I always disagreed with. In my experience, I rather read a short comment explaining what is the purpose of a block of code, than trying to decipher it. Yes, code "should speak for itself", but reading a comment is almost always faster than reading blocks of code.
And then there is also documentation (if you include it in what you define as comment). I much rather go through a website, with a search function, example, description, made with some docgen tool, than having to go through a library or programming language source code every time I need to remember how to do X, or if object B has implement function Y ...
It's just a rule of thumb, like anything else. In most code, "why" is the hard part; I see that you are incrementing that account by a penny from out of the blue, but why? When you are in code where "what" is the hard part, like an implementation of a book algorithm or some tricky performance optimization, then by all means comment that.
Really all this rule amounts to is
// Increment by a penny
accountValue += 1
is a pointless comment, please don't do that. Schools had a way of accidentally teaching that by too-rigidly requiring "commented code", in situations where there wasn't much else to say, or situations where the students themselves didn't necessarily have a strong sense of "why". Any comment that isn't just literally "this is what the next line does" is probably useful to somebody at some point.
I do agree that documenting the why is way more important than the how/what. But having a short comment to summarize a block of code like:
// Parse the filename and remove the extension
let fext_re = Regex::new(r"(.\*)\.(.+)$").unwrap();
let page_cap = fext_re.captures(fname).unwrap();
let page_base_filename = page_cap.get(1).unwrap().as_str();
Is still useful. Instead of having to read the next few line of code, I already know what they are suppose to do and expect.
It makes discovery, later down the line, easier.
This would be entirely self-documenting by replacing that with a function named after what it does, then the comment isn't necessary.
To boot, a unit test could be written that would reveal the bug in the regular expression that makes it only work with filenames that have an asterisk before the extension. Unless you intended that (unlikely), in which case the comment is wrong/not comprehensive and misdirects the reader.
You can put these comments into the name of a function, getting rid of the redundancy and having them read by whoever would just be reading the code not to be distracted by the comments.
> reading a comment is almost always faster than reading blocks of code
Not to a competent programmer when reading well-written code.
This also means that you read what the code does, rather than what a comment says the code does. Otherwise you will be blind to bugs. Any experienced developer will tell you that code very often doesn't do what the original programmer thought it did.
> Not to a competent programmer when reading well-written code.
No, literally reading a one line about what the next 4 lines do is mechanically faster. It does not matter that you are good or bad, it is about simple reading speed.
> This also means that you read what the code does, rather than what a comment says the code does. Otherwise you will be blind to bugs. Any experienced developer will tell you that code very often doesn't do what the original programmer thought it did.
I am an experience developer. I have worked on several "legacy" projects, and started many from 0.
1. It does not make you blind to anything, it is just a way to learn/direct yourself in the code base faster.
2. Knowing what the original developer wanted is often as useful as knowing what the code actually does. More info is better than no info.
Even outdated comment can be useful.
For me, this type of thinking that comment are unnecessary, that competent ppl can just read the code, etc. is actually a sign of younger dev who never had to work on a long-lived codebase.
> For me, this type of thinking that comment are unnecessary, that competent ppl can just read the code, etc. is actually a sign of younger dev who never had to work on a long-lived codebase.
It sounds like you're conflating "helpful comments that explain why" with "no comments are needed ever because read the code", and we're talking past each other.
