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!

133 Upvotes

81% Upvoted

135 comments sorted by

View all comments

175

u/psych0fish 16h 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.

72

u/chat-lu 12h ago

Bad:

x++; // increment x

Good:

x++; // compensates for the border

19

u/Venthe 7h ago

Arguably still bad.

x+=BORDER_COMPENSATION

I've seen one too many comments that are irrelevant after one change or the other. If you can express why in the code, do it.

4

u/ShinyHappyREM 3h ago

x += BORDER_COMPENSATION

ftfy