News for hackers. Stuff that matters.
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.
Re:The Code Documentation Fallacy by JackFr on Thursday October 17, 2013 @10:02AM (#6565361)
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.

Re:The Code Documentation Fallacy by Aykroyd on Thursday October 17, 2013 @02:45PM (#6567344)
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.

Re:The Code Documentation Fallacy by jfb on Thursday October 17, 2013 @12:27PM (#6566381)
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.