Quote:
I understand about the code speaking for itself, but most of the time code can really only speak about the HOW, not the WHY.

This is soooo important. One of my functions at work is to review code written by the rest of our department members. I can't count the number of times that I've seen code that makes me go "huh?" -- the code may be "self-documenting", but not doing what I think it should be doing. The first question I'll usually ask is "why are you doing this?" Sometimes the answer is "well, I tried doing it this [what I would have expected them to do], but it had a problem that doing it this way avoids," to which I'll say "Maybe you could add a comment to that effect, so that whoever maintains this code after you doesn't waste time by ripping it out, and trying to replace it with that." Sometimes I just get a shrug, or an answer that isn't very well thought out -- those are the cases that tell me that a) the developer didn't spend much time thinking about the design, or b) the developer doesn't know the language well enough to know a better way to do it, or c) the code is probably buggy. I've caught a lot of buggy code as a result.

Further, "self-documented code" is sometimes just wrong -- you start out with a function named one thing, which then gets minorly modified so that it subltly doesn't quite live up to its name, but no-one changes the name of the function, because it's an API, and you don't know who else is using the function. Personally, I've never seen any non-trivial so-called "self-documented" code where the "self-documenting" is as complete as it needed to be.

If your comments tell the WHY, and your code tells the HOW, it's a lot easier to make sure that the HOW is actually correct.

On a related note going back to Paul's original comment about incomplete documentation, which spawned this subthread: "documentation" isn't just "commenting code". Documentation encompasses a whole lot more than that, from design specs, to commenting code (algorithms, data structures, code components, etc) to writing end-user documentation.