What code is doing should generally (exceptions are always possible) be evident from the code itself, through clear naming, concise functions with singular goals and proper code structure.
Why code is doing what it does can be helpfully explained through a comment. X may update Y because of business decision Z, so putting a little bit of background info on Z can be very helpful for a future maintainer who might understand what X is doing but might not know why it’s doing so in the first place.
If your code requires a lot of comments to make sense, the comments certainly can be a code smell.
Yesterday I got feedback on my PR asking me to add more XML comments. The userId parameter of type Guid parameter didn’t have a param tag that said that it was the ID of the user.
I was unable to convince them this was unnecessary and eventually conceded by adding a comment userId: ID of user.
See, that to me is an example of a useless comment. The only way I’d justify it is if you have some validation that checks if all public methods have xml comments or something. But userId: ID of user sounds redundant to me.
I agree with what you say (and that is exactly what I meant by “good comments”), but that is not what this fellow’s philosophy was. His philosophy was that all comments are bad no matter what, with no exceptions. In his code reviews, he simply excised all comments, regardless of why they were there and what purpose they served.
What code is doing should generally (exceptions are always possible) be evident from the code itself, through clear naming, concise functions with singular goals and proper code structure.
Why code is doing what it does can be helpfully explained through a comment. X may update Y because of business decision Z, so putting a little bit of background info on Z can be very helpful for a future maintainer who might understand what X is doing but might not know why it’s doing so in the first place.
If your code requires a lot of comments to make sense, the comments certainly can be a code smell.
Yesterday I got feedback on my PR asking me to add more XML comments. The userId parameter of type Guid parameter didn’t have a param tag that said that it was the ID of the user. I was unable to convince them this was unnecessary and eventually conceded by adding a comment userId: ID of user.
See, that to me is an example of a useless comment. The only way I’d justify it is if you have some validation that checks if all public methods have xml comments or something. But userId: ID of user sounds redundant to me.
I agree with what you say (and that is exactly what I meant by “good comments”), but that is not what this fellow’s philosophy was. His philosophy was that all comments are bad no matter what, with no exceptions. In his code reviews, he simply excised all comments, regardless of why they were there and what purpose they served.
That sounds boneheaded. Comments are a feature for a good reason after all.