I've dealt with enough other programmers now to have a better handle on the whole, "self-commenting code" (where there typically aren't any comments at all, not even a flowerbox) versus code documentation issue to know about where I stand. I've noticed that most great programmers don't like to comment their code. I've noticed most mid-rate programmers are big fans of commenting. I've noticed that most crappy programmers don't understand comments they read, much less the code even they themselves write.

Why don't great programmers like to comment and document? That's easy. Which would you rather have... code that works and is designed to anticipate modularity, scalability, etcability, etc or code that's crap but has all its methods and objects carefully commented? To have spent all that time commenting and documenting when your code is still too crappy to use again, and to a great programmer needs to be rewritten anyway, is just a double inefficiency.

Nobody likes (or should like, at least) to use code that they haven't read through and understand if they're going to borrow from it liberally. On the other hand, if you're going to borrow objects and use them as black boxes, all you really care about is that the functions exposed and their parameters are documented and their return values are what you'd expect. Neither case demands great, thorough documentation.

Now if you're a mid-rate programmer that can't understand code, you want it on a silver platter with comments, else you can't figure out enough to use it. Nothing wrong with that. Any level code is better with documentation than without.

But the bottom line is that great programmers want code that works. The end. And if your code isn't spaghetti and is "normalized" (my dba-influenced term for "refactored well") the code will speak for itself.

Anyhow, just some first cuts at this topic. Gotta get back off smoke-break to work, but I'll try to make this vomit of ideas make more sense later.