Quote Originally Posted by techgnome View Post
Exactly my point... EG seemed to indicate that API functions should be so well named along with parameters that we know what each one is that that any further extraneous documentation shouldn't be necessary... and he'd be right if we all had access to all the source code out there... but we don't... so we need that doucmentation at the call level to know what is what.
Wait, so you're saying that if the libraries you used had better interfaces then you wouldn't need documentation? [Edit: re-reading your post, maybe this wasn't your point. If you need to read the source code of a method to know how to call it then, no, it doesn't qualify for not needing comments/documentation.] You may just be on to something there. I don't think that most of the libraries out there are written well enough that you can get away without comments. Certainly pointing out all the poor interfaces with their necessary documentation doesn't invalidate my point one bit.

Let's try this one more time: Don't write the same old code but without comments, write code that doesn't need comments.