Link Details

On the blog, Bill stated, "Documentation obfuscates code, it describes what the author thinks the code will do, and not that what really happens at runtime."

I would like to respond to the statement, not really the individual, here. Documentation does describe what the author thinks the code will do, but more importantly, it describes what he or she wants it to do. This makes it easier to spot where someone made a mistake.

When setting out to create a class or method, I personally find it useful to comment for everything I intend to do. I then write the code around the comments. Often I just delete them, but in other cases, it serves me well to leave some there.

Comments are especially usefull when working in a framework you had no part in planning or creating. "Why did they use this when they could have used that?" You don't know unless there's a comment there. It doesn't mean the comment is necessarily correct, but at least it gives you a sense of what the author had in mind.

OTOH commenting too much causes problems of its own.
If the code is garbage, and worse the comments in it don't reflect the code you have a hell of a time figuring out what's going on.

Had that more than once. A piece of code is broken, the comments on it are broken as well but in a different way.

Actually it depends on a hell of a lot things but!
Commenting code is necessary!
The thing that bothers most of the people when commenting is that they might do the code block well (I mean self documented code here) and for example put in a comment but if the code is procedural style it will really change overtime!
In OOP this wont happen so easily so comments in procedural style might become pain in the ass while in OOP they are a good practice!

Recommend reading about XP (Extreme Programming)!

Cheers!

Finally I agree with jranting on something.

It's similar to the old trick of trying to say the colours that some words are printed in. Easy until the words are also colours, but unrelated colours. (HTML would help here!)

I very rarely comment code, because the compiler doesn't tell me when the comments don't reflect the code. Source code is not a place to put stuff that the compiler won't be parsing.

I'd rather make my source code look how the comment would, if I did write it, or as close as possible.

I'm totally on point no 2. Good code needs very little comments, in key points.

Code is not commented for the same reason that people j-walk. It's not important until you get caught or run over. Then it's too late.

-1 bad analogy

I like commenting codes :).. Without comments, i dont feel the job is done perfectly.