3 ms·

"Comments are bad" is the "fake news!" of programming. Yes, it's reasonable to point out that there are comments that are either inherently bad or become counte

"Comments are bad" is the "fake news!" of programming. Yes, it's reasonable to point out that there are comments that are either inherently bad or become counterproductive as the code moves on without them being updated. OTOH, using those minority examples to cast the whole idea into disrepute is just cherry-picking to rationalize one's own faults. Good commenting complements good code structure, naming, etc. to make code easier to maintain/extend.

MaulingMonkey 8y ago
I've seen code where bad/counterproductive doc comments are the majority examples, not the minority, as a lazy way of meeting some "100% doc comment coverage" mandate. While it still doesn't and shouldn't cast the whole idea into disrepute, they're useful cautionary tales, and a way to help distill down "what makes for a useful comment?" by showing what isn't useful.
- mannykannot 8y ago
  I could only wish that excessive and redundant commenting was somewhere in the top five problems I face in writing software.
  - Bartweiss 8y ago
    I mean, my experience is that these aren't actually opposing problems; it's wretchedly common to find a file where informative comments are scarce, uninformative comments are too numerous, and all the substantive comments are out of date. If code had one problem or the other, we might be able to judge which issue was more common and push people the other way. As is, it tends to have all three diseases at once and I'm not sure what the cure is except screaming "do better!"
    - mannykannot 8y ago
      It is also not uncommon to have code where the various elements do not live up to the claims made in their identifiers. If a programming language is expressive enough to create self-documenting programs, it is expressive enough to imply things that are not true. The point is that if you are not going to trust the words a programmer puts in documentation, then you can't trust the meaning of any words they choose to use in identifiers, either - but if you don't trust the words they use for identifiers, then the code is not self-documenting in any meaningful way. The observation that documentation can be bad does not justify the claim that good code never needs documenting.
    - MaulingMonkey 8y ago
      > As is, it tends to have all three diseases at once and I'm not sure what the cure is except screaming "do better!" Code reviews with people who give a shit helps. I'll commonly suggest specific areas for comment in reviews. And I'll mercilessly delete redundant or just plain wrong comments. Sometimes they were clearly copy+pasted from another method (and thus not right in the first place). I assume they wanted to copy the doc-comment syntax and meant to fix it up later, but then never did...
a1369209993 8y ago
> those minority examples The problem is that those aren't the minority. Comments are like lawyers; there are plenty of good and necessary ones, but 90% of them give the rest a bad name.
foxyv 8y ago
I like to use comments as a sort of punctuation for my code. It's kinda a subtitle for lines that are a bit more involved. Also gives me a chance to reference JIRA tickets which have even more information about why the code is doing what it's doing. Still drives me nuts though to see 10-20 getters/setters in a Java Bean, each annotated with the Javadoc "Gets variableA"

MaulingMonkey 8y ago

I've seen code where bad/counterproductive doc comments are the majority examples, not the minority, as a lazy way of meeting some "100% doc comment coverage" mandate. While it still doesn't and shouldn't cast the whole idea into disrepute, they're useful cautionary tales, and a way to help distill down "what makes for a useful comment?" by showing what isn't useful.

mannykannot 8y ago
I could only wish that excessive and redundant commenting was somewhere in the top five problems I face in writing software.
- Bartweiss 8y ago
  I mean, my experience is that these aren't actually opposing problems; it's wretchedly common to find a file where informative comments are scarce, uninformative comments are too numerous, and all the substantive comments are out of date. If code had one problem or the other, we might be able to judge which issue was more common and push people the other way. As is, it tends to have all three diseases at once and I'm not sure what the cure is except screaming "do better!"
  - mannykannot 8y ago
    It is also not uncommon to have code where the various elements do not live up to the claims made in their identifiers. If a programming language is expressive enough to create self-documenting programs, it is expressive enough to imply things that are not true. The point is that if you are not going to trust the words a programmer puts in documentation, then you can't trust the meaning of any words they choose to use in identifiers, either - but if you don't trust the words they use for identifiers, then the code is not self-documenting in any meaningful way. The observation that documentation can be bad does not justify the claim that good code never needs documenting.
  - MaulingMonkey 8y ago
    > As is, it tends to have all three diseases at once and I'm not sure what the cure is except screaming "do better!" Code reviews with people who give a shit helps. I'll commonly suggest specific areas for comment in reviews. And I'll mercilessly delete redundant or just plain wrong comments. Sometimes they were clearly copy+pasted from another method (and thus not right in the first place). I assume they wanted to copy the doc-comment syntax and meant to fix it up later, but then never did...

a1369209993 8y ago

> those minority examples The problem is that those aren't the minority. Comments are like lawyers; there are plenty of good and necessary ones, but 90% of them give the rest a bad name.

foxyv 8y ago

I like to use comments as a sort of punctuation for my code. It's kinda a subtitle for lines that are a bit more involved. Also gives me a chance to reference JIRA tickets which have even more information about why the code is doing what it's doing. Still drives me nuts though to see 10-20 getters/setters in a Java Bean, each annotated with the Javadoc "Gets variableA"