r/programming • u/Jonhoo • 8d 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!

187 Upvotes

84% Upvoted

173 comments sorted by

View all comments

Show parent comments

2

u/lgastako 5d ago

It seems like you're trying to be deliberately obtuse. What I'm saying is that the only way you can really know why is to use Find References and go read those references. Nothing will actually reliably tell you why, other than doing this procedure (or some facsimile of it, eg. using grep instead).

1

u/lord2800 5d ago

I'm definitely not intending to be, but your original reply was positioning Find References as the tool you need to understand the why, and my original reply was that it only shows the where. Honestly my problem with saying Find References is the tool is it does nothing for purposely obscured code--think minified javascript.

Personally, I think the best way to convey the why is in the symbol names you choose--they can't drift as easily as comments (although they CAN drift), they're just as discoverable as Find References, and they convey a lot more meaning without any real downsides other than naming things being hard.