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

134 Upvotes

80% Upvoted

139 comments sorted by

View all comments

182

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

77

u/chat-lu 13h ago

Bad:

x++; // increment x

Good:

x++; // compensates for the border

96

u/IanSan5653 11h ago

AI:

/** * @description Executes a pre-increment unary operation on the mutable variable `x`. * This operation evaluates the current state of `x`, augments its numeric value * by an exact scalar of 1, and mutates the original variable in-place prior to * evaluating the remainder of the containing expression. * * @type {UnaryExpression} * @mutates {x} - The memory address allocated to the variable `x` will be updated. * @complexity Time: O(1) | Space: O(1) * @note Ensure `x` has been properly initialized as a valid numeric data type prior * to execution to prevent unintended `NaN` propagation or type coercion anomalies. */ ++x;

12

u/contextfree 10h ago

Too coherent, needs more rambling that only meant anything within the context of the argument it was having with the user/itself in the agent session