It’s better to have useful comments. Long odds are that somebody who writes comments like this absolutely isn’t writing useful comments as well - in fact, I’m pretty sure I’ve never seen it happen. Comments like this increase cognitive overhead when reading code. Sure, I’d be happy to accept ten BS useless comments in exchange for also getting one good one, but that’s not the tradeoff in reality - it’s always six hundred garbage lines of comment in exchange for nothing at all. This kind of commenting usually isn’t the dev’s fault, though - somebody has told a junior dev that they need to comment thoroughly, without any real guidelines, and they’re just trying not to get fired or whatever.
Universities often teach students to write a lot of comments, because you are required to learn and demonstrate your ability to translate between code and natural language. But this is one of the things that are different in professional environments.
Every comment is a line to maintain in addition to the code it describes. And comments like this provide very little (if any) extra information that is not already available from reading the code. It is not uncommon for someone to alter the code that the comment is supposed to describe without changing the comment, resulting in comments that lie about what the code does, forcing you to read the code anyway.
It’s like if you were bilingual, you don’t write every sentence in both languages, because that is twice as much text to maintain (and read).
The exception of course, being if you are actually adding information that is not available in the code itself, such as why you did something a particular way.
Yup this is the real world take IME. Code should be self documenting, really the only exception ever is “why” because code explains how, as you said.
Now there are sometimes less-than-ideal environments. Like at my last job we were doing Scala development, and that language is expressive enough to allow you to truly have self-documenting code. Python cannot match this, and so you need comments at times (in earlier versions of Python type annotations were specially formatted literal comments, now they’re glorified comments because they look like real annotations but actually do nothing).
If I see comments explaining every other line, especially describing “what” instead of “why”, I assume the code was written by a recent grad and is going to be bad. Describing what you are doing looks like you are doing a homework assignment.
Like on that line, obviously we’re initializing a variable, but why 1 instead of 0? Could be relevant to a loop somewhere else, but I guess I’ll have to figure that out by reading the code anyways.
It’s like if you were bilingual, you don’t write every sentence in both languages, because that is twice as much text to maintain (and read).
This is a very good analogy. And just like with natural languages, you might have an easier time expressing an idea in one language but not the other. Comments should provide information that you find difficult to express with code.
If there are too many comments, it means you have to support them just like the code itself. Otherwise, like any other documentation, comments will quickly go out of sync.
I mean, it’s better to have to many comments than not enough
It’s better to have useful comments. Long odds are that somebody who writes comments like this absolutely isn’t writing useful comments as well - in fact, I’m pretty sure I’ve never seen it happen. Comments like this increase cognitive overhead when reading code. Sure, I’d be happy to accept ten BS useless comments in exchange for also getting one good one, but that’s not the tradeoff in reality - it’s always six hundred garbage lines of comment in exchange for nothing at all. This kind of commenting usually isn’t the dev’s fault, though - somebody has told a junior dev that they need to comment thoroughly, without any real guidelines, and they’re just trying not to get fired or whatever.
Wonderfully said, I’ll be linking your response
Universities often teach students to write a lot of comments, because you are required to learn and demonstrate your ability to translate between code and natural language. But this is one of the things that are different in professional environments.
Every comment is a line to maintain in addition to the code it describes. And comments like this provide very little (if any) extra information that is not already available from reading the code. It is not uncommon for someone to alter the code that the comment is supposed to describe without changing the comment, resulting in comments that lie about what the code does, forcing you to read the code anyway.
It’s like if you were bilingual, you don’t write every sentence in both languages, because that is twice as much text to maintain (and read).
The exception of course, being if you are actually adding information that is not available in the code itself, such as why you did something a particular way.
Yup this is the real world take IME. Code should be self documenting, really the only exception ever is “why” because code explains how, as you said.
Now there are sometimes less-than-ideal environments. Like at my last job we were doing Scala development, and that language is expressive enough to allow you to truly have self-documenting code. Python cannot match this, and so you need comments at times (in earlier versions of Python type annotations were specially formatted literal comments, now they’re glorified comments because they look like real annotations but actually do nothing).
Exactly! Write your code to be as clear and self-descriptive as possible, and then add a comment if something is still not immediately obvious.
If I see comments explaining every other line, especially describing “what” instead of “why”, I assume the code was written by a recent grad and is going to be bad. Describing what you are doing looks like you are doing a homework assignment.
Like on that line, obviously we’re initializing a variable, but why 1 instead of 0? Could be relevant to a loop somewhere else, but I guess I’ll have to figure that out by reading the code anyways.
This is a very good analogy. And just like with natural languages, you might have an easier time expressing an idea in one language but not the other. Comments should provide information that you find difficult to express with code.
If there are too many comments, it means you have to support them just like the code itself. Otherwise, like any other documentation, comments will quickly go out of sync.
Legit, I’ll take this over the undocumented spaghetti I too often see written by “professionals”.