Am 14.10.2004 um 20:07 schrieb Tim Rowledge:

> Blake <blake at kingdomrpg.com> wrote:
>
>> I'm anti-comment, myself, with some rare exceptions. Documenting the 
>> class
>> as a whole might make sense, but comments for each 
>> method--particularly in
>> Smalltalk--seems, well, redundant.
>
> Wrong, wrong, wrong. Did I say 'wrong'?
>
> Whilst a few small methods might be completely self explanatory as to
> what they actually do, it is extremely rare that this is a complete
> explanation of what the code is _supposed_ to do. I claim that the
> fantasy of 'self commenting code' is just that - a fantasy. Usually
> promulgated by lazy buggers that take the attitude summed u in one of
> my auto-magic siglines "Comments? Why do you think it's called code?"
>
>

There is another important reason for comments: They provide 
re-inforcement
that the understanding of the code that the reader gets is correct. For 
me,
this just helps to read code fast. I think this is the same reason why 
we repeat
a lot when writing words (e.g. a thesis): Say what you will say, say 
it, say what
you have said. This feels pretty awkward when writing, but the 
*reading* gets
improved a lot. People read the repetition not as "he said that 
allready" but
"yes, looks like I understood it correctly".

Of course, writing good comments, like all writing, is hard. Harder 
than programming, I
think.

       Marcus