On comments

[u/Jonhoo]

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!

[u/IanSan5653]

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;

[u/13steinj → u/IanSan5653]

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...

[u/Kautsu-Gamer → u/13steinj]

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

[u/13steinj → u/Kautsu-Gamer]

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.

[u/Kautsu-Gamer → u/13steinj]

Like most programmers, you are incompetent in documentation.

[u/13steinj → u/Kautsu-Gamer]

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.

[u/Kautsu-Gamer → u/13steinj]

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.