Re:The Code Documentation Fallacy
by lyesit on Thursday October 17, 2013 @08:33AM
(#6564909)
I think the argument being made is that comment quality is more important than quantity. The author gave an example where the code with less documentation had more useful descriptions in order to illustrate this point; I don't think he necessarily meant that one caused the other.
[ Parent
| on HN ]
Re:The Code Documentation Fallacy
by jaimebuelta on Thursday October 17, 2013 @08:49AM
(#6564985)
I can't see why 90% of the functions cannot be properly commented. In the example, the "good" documentation is, by the way, probably less work than the verbose "bad" one.
And, in my experience at least, very few times the comments are out-of-date with the code. If that's the case, once is detected, it should be treated as a bug. Fix/remove the comment.
Re:The Code Documentation Fallacy
by TheDistantSea on Thursday October 17, 2013 @08:40AM
(#6564950)
That's something we can all agree on, but then why bring quantity into the discussion? I prefer lots of useful comments over few useful comments.
To paraphrase The Incredibles, if everyone is special, than no one is.
If 10% of the functions are commented, I will assume that those 10% are more important or have more error prone or dangerous usages. If every function has a boilerplate comment, I lose that information.
You can catch garbage comments in code reviews just as easily as you can catch other forms of programming garbage during review. The fact that someone might make a lot of bad comments is not a good argument against commenting, it's a good argument against bad commenting.
I also think that if people are in the habit of having to comment it makes them more likely to document things like expected values of the input, what the return could be expected to be, and if there are any caveats.
Nobody is arguing for boilerplate. The idea that less is more, holding quality equal, is nonsensical. Of course, as documentation isn't free, you can't hold quality equal, so it's immaterial -- nobody is ever going to be presented with that choice in real life.