This is a straw man. Code, comments, and documentation are documents meant for different audiences. Code is meant for the computer first and the developer second. Comments are meant to clarify for the developer when code is difficult to read. Documentation is meant for the user. I find it very ... rude ... when a developer documents private functions. I don't want to know them! I want to know the interface I'm meant to use. If I want to contribute back to your product, I will read the code and the comments. That's when I'll find the private functions and funky variables. If a piece of code violates accepted norms, then it should be commented. If it does something really wonky, it should be commented. Otherwise, you shouldn't say anything at all. Too many comments are often worse than none at all.
in reply to The sourcecode *is* the documentation, isn't it?
We are the carpenters and bricklayers of the Information Age.
Then there are Damian modules.... *sigh* ... that's not about being less-lazy -- that's about being on some really good drugs -- you know, there is no spoon. - flyingmoose
I shouldn't have to say this, but any code, unless otherwise stated, is untested