Hacker News Reader

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.

View on HN

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.

Reply on news.ycombinator.com