In my experience, most teams are not operating at a level of comment saturation where we can worry about this kind of thing.
It can be hard enough to get folks to accept that their code isn’t “self-documenting” and actually write some comments to help the person who inherits their code orient themselves.
Often the comment author and comment reader are the same person, but separated temporally by all the time that has passed since the code was last read, understood, and internalized, so the two may as well be entirely different people.
As a note, I’m usually hesitant to refer to a specific variable name in a comment because code changes and comments aren’t always kept up to date, so you might actually be introducing more confusion in the future when someone renames a variable and no one notices that the comment is out of sync.
I agree 100% with your observation about most teams, and how hard it is to get people to write comments that aren't on the level of `# increment i`.
I also like your tip about not putting specific variable names in comments. I'll have to think about that. It's hard to describe trick pieces of algorithms without naming names, though.
Maybe the article should be read as hints to folks who are trying hard to write understandable comments. As an example, I try to write comments without the "to be" verb, because I find using "to be" forms decreases the reader's chances of distinguishing variable type from its contents, and action from actor. Would I impose this on my team? Never.
In my experience, most teams are not operating at a level of comment saturation where we can worry about this kind of thing.
It can be hard enough to get folks to accept that their code isn’t “self-documenting” and actually write some comments to help the person who inherits their code orient themselves.
Often the comment author and comment reader are the same person, but separated temporally by all the time that has passed since the code was last read, understood, and internalized, so the two may as well be entirely different people.
As a note, I’m usually hesitant to refer to a specific variable name in a comment because code changes and comments aren’t always kept up to date, so you might actually be introducing more confusion in the future when someone renames a variable and no one notices that the comment is out of sync.
I agree 100% with your observation about most teams, and how hard it is to get people to write comments that aren't on the level of `# increment i`.
I also like your tip about not putting specific variable names in comments. I'll have to think about that. It's hard to describe trick pieces of algorithms without naming names, though.
Maybe the article should be read as hints to folks who are trying hard to write understandable comments. As an example, I try to write comments without the "to be" verb, because I find using "to be" forms decreases the reader's chances of distinguishing variable type from its contents, and action from actor. Would I impose this on my team? Never.
I loved this footnote:
"That’s right, I’m the first person to admit that I shouldn’t have written this newsletter to begin with."