Re^2: The sourcecode *is* the documentation, isn't it?

[adrianh]

Let the source code say what you are doing, add comments to say why you are doing it

I'd go a bit further and say that if you have to add comments to explain why you're doing it you should reconsider and see if there way you can rewrite your code to express your intentions more obviously.

Comments are a good thing if they make non-obvious code easier to understand. Even better is to make the non-obvious code more obvious.