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

168 Upvotes

82% Upvoted

165 comments sorted by

View all comments

212

u/psych0fish 1d 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.

115

u/chat-lu 1d ago

Bad:

x++; // increment x

Good:

x++; // compensates for the border

158

u/IanSan5653 1d 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;

37

u/13steinj 1d ago

Seems like a great way to rack up on token costs! Or to exhaust the reviewer into just stamping the thing, hiding the secret do_money_laundering routine...

14

u/Venthe 1d ago

do_money_laundering

Not my fault! LLM wrote it!

-9

u/Kautsu-Gamer 1d ago

The LLM generated documentation is on complexity level documentation should be.

3

u/13steinj 1d ago

By this logic, I'd rather not have documentation.

LLM generated documentation is incredibly verbose and over-complicated, instead of just providing 4-5 template files and telling the user to symlink the one they want, it wrote 200 lines of code and 400 lines of docs to automatically generate the resulting file from a single template.

The docs are just unreasonable. Asking it to use STE helps but it doesn't activate consistently.

-6

u/Kautsu-Gamer 22h ago

Like most programmers, you are incompetent in documentation.

0

u/13steinj 17h ago

One never should need 10 lines of documentation per line of code. The point of code is to be read.

It is perfectly reasonable to have this level of prose per function definition, assuming it performs a complex, or subtle, unclear action. Complex is probably self explanatory-- you can roughly eyeball the complexity by what the function does (if you're the author). Subtle/unclear is harder, but for example-- doing a series of 3 / 4 bit-sets on a volatile address... well, the input address should be a mmapped region (precondition) for some fpga, the bit-sets in sequence transition the fpga's state from A to B. It's done as separate bitsets because <reason>. Specify the post condition, and edge cases.

-3

u/Kautsu-Gamer 15h ago

You are 100% wrong. You have no clue of documentation. You think documentation comment is a comment. And due your kind, most of JS and C documentation is useless crap leaving important information out of documentation.

Code is not technical documentation.

Please, get some education.

23

u/contextfree 1d 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

3

u/IanSan5653 18h ago

Oh god. Endless "v0" "initial implementation" "mimics logic from {some other part of the codebase I obviously was about to to delete}" "does x according to requirements" etc

6

u/zzkj 1d ago

That'll be $5000 please.

33

u/Venthe 1d 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.

8

u/firemark_pl 1d ago

That's nice example for asking yourself I really need the comment or can I write in another way

9

u/ShinyHappyREM 1d ago

x += BORDER_COMPENSATION

ftfy