Hi Stefan

>What's actually happening (barring corrupt indexes and things like that *g*) is already written down precisely: in the form of source code statements. What is not always apparent from the code is what is supposed to accomplish, namely the intent. For example, when a statement or command has several consequences (affects program state in more than one way) then it is not always obvious which ones of these consequences are intended and which ones are incidental; also, the manner in which these consequences are used is not always apparent. That is why code sometimes needs to be supplemented with comments for the benefit of human readers. In fact, I would consider such comments an inseparable, necessary part of good source code.
>

And I would not disagree with you one iota! The issue is where should the documentation go, and where should the comments go? I agree with Rick that comments belong in the code, but documentation should normally separated from the code itself.