I love the article, but hate the title.
Too many people read these comments-considered-harmful types of articles and mistakenly believe that all comments are bad, which is definitely not the case. In my career I've been annoyed by under-commented code more often than by over-commented.
Having said that, I pretty much agree with everything you said (apart from the title) and I found it quite well written.
The example you give under "Noise Comments" is interesting. It's a common coding standard in Java to generally avoid empty catch blocks, and, in cases where an empty catch block is justified, to include a comment in the block explaining why. If that's a real-world example, I'm guessing that the build system included a checkstyle plugin which enforced that rule, and that the "Give me a break" comment is there to circumvent it. If so, I think that developer's problems go beyond just poor commenting skills! :-)
Well as they say don't judge a book by its cover 😅
If someone got through the first passage thinking that they should not be commenting their code at all they missed the point completely, we both agree that we always should try to write better code with less noise and more valuable comments to make fellow programmers' life easier in the future
I agree that this is a great article, but also agree with David about the title. Unfortunately most people don't actually fully read an article and they will miss the point in the beginning.
I've had many devs share articles like this with me for a reason to not write comments and didn't realize the first paragraph was saying that some comments are good anyways. They only read the subheadings really.
I saw in another comment that you might write another article about which comments to write and I would highly recommend doing that.
It could also be good to include that some times some of the comments you mentioned here as bad could be good. For example mandated comments are good for public packages, APIs, build and code style / generation tools, etc.
I was also arguing that Java doc in public packages, like Java official documentation is Good and needed.
Even better if some example and useage is in the documentation.
In internal methods, classes only for internal use, not so much.
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 love the article, but hate the title.
Too many people read these comments-considered-harmful types of articles and mistakenly believe that all comments are bad, which is definitely not the case. In my career I've been annoyed by under-commented code more often than by over-commented.
Having said that, I pretty much agree with everything you said (apart from the title) and I found it quite well written.
The example you give under "Noise Comments" is interesting. It's a common coding standard in Java to generally avoid empty catch blocks, and, in cases where an empty catch block is justified, to include a comment in the block explaining why. If that's a real-world example, I'm guessing that the build system included a checkstyle plugin which enforced that rule, and that the "Give me a break" comment is there to circumvent it. If so, I think that developer's problems go beyond just poor commenting skills! :-)
Well as they say don't judge a book by its cover 😅
If someone got through the first passage thinking that they should not be commenting their code at all they missed the point completely, we both agree that we always should try to write better code with less noise and more valuable comments to make fellow programmers' life easier in the future
I agree that this is a great article, but also agree with David about the title. Unfortunately most people don't actually fully read an article and they will miss the point in the beginning.
I've had many devs share articles like this with me for a reason to not write comments and didn't realize the first paragraph was saying that some comments are good anyways. They only read the subheadings really.
I saw in another comment that you might write another article about which comments to write and I would highly recommend doing that.
It could also be good to include that some times some of the comments you mentioned here as bad could be good. For example mandated comments are good for public packages, APIs, build and code style / generation tools, etc.
I was also arguing that Java doc in public packages, like Java official documentation is Good and needed.
Even better if some example and useage is in the documentation.
In internal methods, classes only for internal use, not so much.