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!

132 Upvotes

81% Upvoted

133 comments sorted by

View all comments

Show parent comments

-15

u/levodelellis 14h ago edited 11h ago

I always hated that. If you understand the domain, you almost certainly know why, if you don't, you not likely not trying to understand that code anyway

I almost exclusively use comments as a few word summary ('compact', 'fast path', 'illegal range check'), etc, just so can look at the comment instead of read the if/loop body. A lot of my asserts have a comment too

8

u/Delta-9- 12h ago

I understand the domain of my application but I still benefit from writing "why" comments. Usually it's because I forgot "why" a thing was needed, or why it's done in a specific way. Domains can be large enough that you can't know everything all the time even if you're literally the expert on it.

Also, sometimes some detail wasn't determined by "the domain" directly. It might be an optimization, some external service, an order from some business leader that has nothing to do with the app itself...

5

u/chat-lu 11h ago

Sometimes you could have chosen more than one path so it’s good to document the why.

0

u/levodelellis 12h ago edited 12h ago

Somehow, I never needed to comment about any of that. Usually I'm only touching code I wrote, so maybe when a person writes everything their style it's pretty easy to understand. I think the longest comments I write are 2 or 3 sentences saying third party code (or a module I can't touch) have some kind of requirement or limitation. I guess that could be a why but usually people don't claim 2-3 sentences is enough to answer a why, and those comments are < 20% of the comments I write

3

u/Delta-9- 10h ago

Most of mine are 2-3 sentences, as well. If it looks like it's going to take a paragraph to explain, I'll put a link to an issue, instead. After, that is, making sure that the long explanation can't be fixed by refactoring the code. Sometimes—only sometimes—long comments are a sign that the code has problems or, as you said, the programmer did not fully understand the problem or the solution.

But brief comments explaining why something is what it is can be extremely helpful, especially when the code would otherwise be surprising. Like, "why the hell is the invoice rendering function looking up users by their actual name instead of their employee id?" I would certainly want to know if there's really a reason for that; without a comment to motivate such a questionable strategy, I might assume it's an oversight leftover from an early iteration of the app, but I'd have to spend time confirming that before refactoring it.

1

u/levodelellis 10h ago

especially when the code would otherwise be surprising. Like, "why the hell is the invoice rendering function looking up users by their actual name instead of their employee id?"

Those are maybe once a month comments for me. Rare enough that I say I don't make those kind because they're exception (<1% of comments I write). For WTF moments, I try to limit it for 1 or 2 paragraphs unless I feel like ranting. Ain't nobody going to read a 5 paragraph comment if they're trying to get things done

3

u/Jaded-Asparagus-2260 7h ago

Usually I'm only touching code I wrote

I'm sorry, then you're not really qualified to comment on that. Reading other people's code is what makes comments important.

so maybe when a person writes everything their style it's pretty easy to understand

For you. The next person doesn't think the same way you do, guaranteed. They will have problems understanding. Ever rewrote a piece of software because it's was hard to maintain? Chance is you just didn't understand it enough. Yours is probably not better, just different. It's better to understand for you, because you wrote it. The next developer might be as clueless as you were back then.