Quote:

Quote:
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.

The name of the function might lie, but the code inside it wont.

Now, suppose there's a bug in the code, so that it's doing something yet even more different -- you have a function named for something it's not really doing, the original programmer's intent is to do something that the code's not actually doing -- without a comment explaining what the intent was, are you, the maintainer, going to guess at the code's intent, or just incorrectly fix it to do what the name of the function is?

Quote:
I don't see how a comment could be any better, after all your programmer might forget to change the comment, or the comment might get shifted from its original place after code edits, imho it's far easier to get comments out of sync with code than "code"!

That's partly why it's so important -- if the comments match the code, then you know it's more likely things are hunky-dory. If the comments don't match the code, then you and the developer need to have a chat, because it's an indicator that he didn't write what he intended to write.

In addition, tons of research has been done that shows commenting code does improve maintainability and code readability. Welcome to the field of software metrics analysis. Several years ago, I spent 8 months as an intern with a the Software Engineering and Analysis Lab at Nortel (I can't find an external web-presence for them, but there's an description for them here).
Lots of statistics; I couldn't hack it, and had to get out.

In general, I treat blocks of code as a paragraph, and, just like paragraphs have an introductory sentence, I typically add a summary comment about what the block of code is supposed to be doing, and why. Line-by-line commenting is excessive, and metrics analysis shows that too much commenting can be just as bad as too little.