Code documentation is like sex, when it's good it's great, and when it's not good...it's still better then no documentation.
I disagree. When comments are essentially just a rephrasing of the class/method name or arguments it is not helpful and anything that is not helpful is cluttering up the code and making it harder to quickly see what the code is doing. I'd rather have no comments than comments like that.
I reserve comments for explaining why a section of code is needed or explaining how a complex algorithm works.
i = 0; // Set i to 0 is pointless.
if (last_output_vertex[i] == bounds[i]->length - 1) contibuting_bounds[i] = NULL; // stop outputting a bound if the entire bound has been output is helpful.
Comments can also be useful for explaining what the code is intended to do when debugging.
"Hey this function says it should return the number of apples, but looks like someone, not saying who, but someone had a brain fart and typed oranges in one variable. Who wrote this code anyway?"
I think even the second comment is not that helpful.
Just use (boolean) variables that phrase what your comment would explain, often more concise and better to read IMO. Also if the logic is more complex compose multiple named (boolean) variables. I think comments seldom make any sense at all (function doc is a one of the rare cases, mostly for the user of the library in the IDE).
Not to mention the code and comment will inevitably become inconsistent with each other whenever someone forgets to update both.
how is that like sex
You would know if you had sex
fair enough
And if you’re male.
Edit: FFS does no one realize that women experience sex differently from men? Bad sex with an oblivious partner can be downright painful for a woman. The same is typically not true for men. My point was not that women don’t have sex or that they don’t enjoy sex. My point is that they don’t experience it the same way as men.
Code documentation is like sex, when it's good it's great, and when it's not good...it's still better then no documentation.
I disagree. When comments are essentially just a rephrasing of the class/method name or arguments it is not helpful and anything that is not helpful is cluttering up the code and making it harder to quickly see what the code is doing. I'd rather have no comments than comments like that.
I reserve comments for explaining why a section of code is needed or explaining how a complex algorithm works.
i = 0; // Set i to 0is pointless.if (last_output_vertex[i] == bounds[i]->length - 1) contibuting_bounds[i] = NULL; // stop outputting a bound if the entire bound has been outputis helpful.Comments can also be useful for explaining what the code is intended to do when debugging.
"Hey this function says it should return the number of apples, but looks like someone, not saying who, but someone had a brain fart and typed oranges in one variable. Who wrote this code anyway?"
-Last edited by JonEFive in 2021-
Past me sucks.
https://github.com/jayphelps/git-blame-someone-else/
I think even the second comment is not that helpful.
Just use (boolean) variables that phrase what your comment would explain, often more concise and better to read IMO. Also if the logic is more complex compose multiple named (boolean) variables. I think comments seldom make any sense at all (function doc is a one of the rare cases, mostly for the user of the library in the IDE).
Not to mention the code and comment will inevitably become inconsistent with each other whenever someone forgets to update both.
how is that like sex
You would know if you had sex
fair enough
And if you’re male.
Edit: FFS does no one realize that women experience sex differently from men? Bad sex with an oblivious partner can be downright painful for a woman. The same is typically not true for men. My point was not that women don’t have sex or that they don’t enjoy sex. My point is that they don’t experience it the same way as men.
I thought women have sex too
Women don't exist
!womenarentreal@lemmy.world
No you don't exist!
None of us exist. Does that settle it?
We're all NPC's in some grand simulation running on a server in a warehouse long forgotten about and abandoned by the gods.