this post was submitted on 14 Mar 2025
653 points (99.0% liked)
Programmer Humor
21487 readers
1507 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
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
Mmmm kind of? I wouldn't categorize most comments as describing "extremely weird" reasons, though. Code will generally explain the "how", while comments can describe the "why". For example, think of an enum with ViewSize "mini" and "full". It might be nice to have a comment to briefly summarize what ViewSize is meant to represent, and maybe link to a spec. Basically, a comment here will connect the intention with the implementation.
A more inline-comment example of this might be if there's a slightly nuanced case that you want to be very clear about, ala maybe a Javascript true/false/null case, where you might be checking === false, and specifically don't want someone to refactor it into a falsy check. Kind of contrived example , but that sort of thing. This is probably more the "extremely weird" comment you're talking about; almost just a warning that this might not be what you think it is.
The other common use-case I find good for comments is for summarizing the goals/purpose of a complex function. This is mostly for future people who might utilize this function, and don't want to read through a bunch of code, just to remember the nuances of what it's supposed to do. For example, a "sortEvents" function, you may want to summarize the business requirements of the sort at the top. Although, this kind of thing may be different depending on how documentation is stored.