4 ms·

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" m

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

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