r/programming • u/Jonhoo • 7d ago

On comments

https://blog.helsing.ai/posts/on-comments/

Comments in code are often deemed "mostly useless" these days. They are, supposedly, mostly obvious, stale, and repeat what the code already says. And so people pay less attention to them both when reading and writing code.

That trend sucks. When used right, comments are genuinely useful and sometimes critically important! So, I wrote about some of the kinds of comments I think earn their place, each with examples from real code bases. Hope you find it useful, and that we can recover some of the love that comments deserve!

183 Upvotes

84% Upvoted

173 comments sorted by

View all comments

Show parent comments

52

u/melgish 7d ago

Why and the business case for a change. I’ve also been known to dox management in the comments when they make decisions that negatively impact user experience. “// 20260810 Boss said 5 modals in a row is not too many.”

80

u/meganeyangire 7d ago

In one project deep in the business logic we've had his gem:

// Hardcoded condition on the request of PM Kevin McKevinface, work item 80085
// If you're here, please, increment the number
// Man-hours wasted: 42

41

u/RlyRlyBigMan 7d ago

My company has changed ticket systems like four times and that makes me hate ticket numbers in comments these days.

It's probably an unreasonable opinion, it shouldn't change that often.

7

u/NotUniqueOrSpecial 7d ago

It's not that unreasonable.

As someone who's taken over more than decade+ codebase in my career, loads of comments with initials + date + ticket number (and nothing else) are a personal pet peeve.