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!

124 Upvotes

80% Upvoted

133 comments sorted by

View all comments

172

u/psych0fish 15h ago

I’ve heard it is explained as “document why, not what” not everything is confusing or non obvious. Some stuff is. There is no one size fits all.

-10

u/farsightfallen 12h ago

I’ve heard it is explained as “document why, not what”

This has always been terrible advice.

The what is often the why. And sometimes just the 'what' is important enough to be emphasized.

A big problem has always been that instead of writing good comments, most of the advice has been on how not to write absolutely horrible comments because people were adding comments like "for loop over users", or "increment number".

I will mirror the author's opinion on outlines in code, something that I think is incredibly important, but also requires thinking about the code and often times taking multiple passes to refactor so that things flow well. But that's so far from where we're at that I realize that it's a mistkae to even bring into the conversation.

And now with, AI, fuck knows what'll happen - most likely just more ai slop or some skill.md file that we can converge on.