I highly recommend taking a look at Clean Code by Robert C. Martin (a.k.a. Uncle Bob).
The author argues there's no such thing as good comments as the very fact you need them often indicates the code might've been written in a confusing way. Strive at writing simple, well-structured code that adopts good naming conventions and in most cases this will be enough to steer clear of cluttering the code with comments.
Another major issue is they tend to get out of sync with the code: imagine a developer making a change a few months down the line, forgetting to update the comment above. You then look at the file in confusion as you're not sure whether it's the comment or the actual code that's correct. I've been in this kind of situations many, many times.
I agree for the most part that you should explain the "why not what" but of the four things you list above, you might argue that
What it does - agree
System interconnection does not belong in the comments unless it that part of the code is orchestrating the interconnection and the code is unable to make that clear. Comments like "This will be use by x for y" may not be useful as other components using this code may change what they do leaving the comment stale.
Product usecases are really not appropriate for a comment in my view unless they are used directly to build/generate the documentation (for example using a tool like Docular).
Changes over time - If done wrong this can leave a lot of stale information in the source that someone skimming over might draw incorrect conclusions from. If it is felt there is a need to write this is the code in comments it suggests to me that the commit log is not being maintained well for that code. Good commit log messages leads to a good story of what changed and why. I'd argue that writing good commit messages is more important with respect to changes over time.
As a side note, for this if using git, learn interactive rebasing... it is in my view the path to a readable commit log.
I'm all for having the minimum amount of comments necessary.
Also, there are lots of good reasons to have comments. Sometimes, you're at the boundaries of systems. Made-up example: you have to pass an empty object instead of a null or the other way around for whatever reason the other system (that you might not control) expects. You leave a comment. It's not about making a comment "I'm returning a null", it's about "I'm returning a null because the other library is behaving badly with an empty object or whatever."
Sometimes, you think a code might be easily refactored, but you plunge in it and several dependent classes later you realize there are justified reasons why the code is written a certain way. A small comment can save hours to the next scout who wants to "leave the campground cleaner."
Or, you're choosing a particular hashing algorithm for certain useful or important properties for your use case. Please leave a comment explaining why. If not, someone else might just modify it for a more popular algorithm without realizing the unexpected impact in performance and of security.
Especially in shops or projects with high turn-over or which lives for decades, history and business logic gets lost.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I highly recommend taking a look at Clean Code by Robert C. Martin (a.k.a. Uncle Bob).
The author argues there's no such thing as good comments as the very fact you need them often indicates the code might've been written in a confusing way. Strive at writing simple, well-structured code that adopts good naming conventions and in most cases this will be enough to steer clear of cluttering the code with comments.
Another major issue is they tend to get out of sync with the code: imagine a developer making a change a few months down the line, forgetting to update the comment above. You then look at the file in confusion as you're not sure whether it's the comment or the actual code that's correct. I've been in this kind of situations many, many times.
i don't buy the "good code doesnt need comments" anymore
even the best code can't explain oddities in partner libs or complicated domain logic
and i have yet to meet a company that never changes it's product and achieves "best code" over a longer time.
code has several dimensions:
good code can explain the first dimension
barely the second
hardly the 3rd
almost never the 4th
thus: "explain why not what"
I agree for the most part that you should explain the "why not what" but of the four things you list above, you might argue that
What it does - agree
System interconnection does not belong in the comments unless it that part of the code is orchestrating the interconnection and the code is unable to make that clear. Comments like "This will be use by x for y" may not be useful as other components using this code may change what they do leaving the comment stale.
Product usecases are really not appropriate for a comment in my view unless they are used directly to build/generate the documentation (for example using a tool like Docular).
Changes over time - If done wrong this can leave a lot of stale information in the source that someone skimming over might draw incorrect conclusions from. If it is felt there is a need to write this is the code in comments it suggests to me that the commit log is not being maintained well for that code. Good commit log messages leads to a good story of what changed and why. I'd argue that writing good commit messages is more important with respect to changes over time.
As a side note, for this if using git, learn interactive rebasing... it is in my view the path to a readable commit log.
I'm all for having the minimum amount of comments necessary.
Also, there are lots of good reasons to have comments. Sometimes, you're at the boundaries of systems. Made-up example: you have to pass an empty object instead of a null or the other way around for whatever reason the other system (that you might not control) expects. You leave a comment. It's not about making a comment "I'm returning a null", it's about "I'm returning a null because the other library is behaving badly with an empty object or whatever."
Sometimes, you think a code might be easily refactored, but you plunge in it and several dependent classes later you realize there are justified reasons why the code is written a certain way. A small comment can save hours to the next scout who wants to "leave the campground cleaner."
Or, you're choosing a particular hashing algorithm for certain useful or important properties for your use case. Please leave a comment explaining why. If not, someone else might just modify it for a more popular algorithm without realizing the unexpected impact in performance and of security.
Especially in shops or projects with high turn-over or which lives for decades, history and business logic gets lost.