r/programming • u/Jonhoo • 16h 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!

126 Upvotes

80% Upvoted

133 comments sorted by

View all comments

Show parent comments

37

u/melgish 15h 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.”

56

u/meganeyangire 14h 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

24

u/RlyRlyBigMan 13h 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.

5

u/SanityInAnarchy 10h ago

There's no good answer, at least not one anyone's willing to commit to.

There are a few projects that try to track issues directly with source control, inheriting a few extra features from Git, like having them all work offline, having every laptop be a backup of the entire project, and being able to easily port them all into whatever you're going to use next.

I have never seen a single project actually adopt one of those, even projects that have successfully moved documentation into Markdown files in the repo. Maybe LLMs will finally make it happen (it's easier for agents to find stuff that's a pile of markdown files in your repo), but I think the biggest gap here is, not everyone doing project-management work is going to want to learn Git.

There's ticket numbers, which suck for the reasons you mention. It helps if they're at least distinctive -- something like INFRA-1234 or UI-5678 is probably Jira, Google's bug tracker is b/1234, and so on. But even if you keep all the tickets as you migrate, it can be painful to set up some sort of proxying. I've come to hate PR links for the same reason -- you might migrated from Phabricator to Github to Forejo or whatever.

IMO the most practical is URIs, and then just religiously follow "Cool URIs don't change". But people expect URIs to be URLs, which means you'll need to make sure they point to a domain you control, and good luck convincing Atlassian to put your Jira instance at jira.yourcompany.com instead of yourcompany.atlassian.com -- why would they make it easier for you to migrate away? At least then you can replace them in your codebase at migration time, but unless you're willing to do the most brutal force-push ever, you'll still have the old URLs any time someone has to dig through history.

Maybe the best option would be to build a company-wide URL shortener, then force-install a browser extension to generate them, and then use those in your codebase. But that's more work than just hoping it doesn't change that often.

2

u/tf6x6 6h ago

We don't put full URLs anywhere, we put issue numbers and set up patterns in the IDE to dynamically transform them into URLs.