618
4 out of 5 developers
(files.techhub.social)
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
this post was submitted on 24 Sep 2025
618 points (99.5% liked)
Programmer Humor
28343 readers
764 users here now
Welcome to Programmer Humor!
This is a place where you can post jokes, memes, humor, etc. related to programming!
For sharing awful code theres also Programming Horror.
Rules
- Keep content in english
- No advertisements
- Posts must be related to programming or programmer topics
founded 2 years ago
MODERATORS
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.
That sounds boneheaded. Comments are a feature for a good reason after all.