[CodeMage]

The point on API methods is incredibly important. True, "Why" is the most important kind of comment, but I disagree with the author's critique of the documentation-generating comments and agree with you.

Yes, "what" comments are a source of additional developer effort and of possible inconsistencies between code and comments, but good API documentation is worth writing and maintaining.

No matter how well you name your method and its arguments, if it's part of the public API and you don't include a comprehensive documentation comment, I'll be forced to dig through your source.