=?ISO-8859-1?Q?st=E9phane_ducasse?= <ducasse at iam.unibe.ch> wrote:
> Hi goran
> 
> You are totally right. Now what can we do if people do not care?
> We can say that we do not harvest code if there are no comments. But 
> this is also not really satisfactory.
> ;(((( sad day.
> 
> Stef
Hi Stéphane!

I read the whole thread and since no one else seems to be doing it...
What the hell, let's play the devil's advocate. ;-)

With all respect, I disagree!

To support my heretic position I offer several observations and one
possible explanation:

- There are many programmers, for whom code quality is very important
but comments are not. How do you explain that fact? That they are all
either stupid or lazy? I find that argument not very convincing.

- There are a lot of easily understandable classes without comments. And
the opposite is true as well. From what I have seen - and I have seen a
lot of (mostly bad) code - I would not conclude there is a positive
correlation of code quality and the rate of commenting. I would rather
think the opposite is more likely.

- A high percentage of exisiting comments do either not add any relevant
information, or the code could be easily refactored so that this would
be the case.

- Developers who write bad code also write bad comments. Bad comments
are not only not helpful, most of the time they are even obscuring the
meaning of the code, distracting or hiding bugs. They lure you into
thinking you might get away without reading the code.

- Comments are a form of redundancy. And redundancy has some advantages
but also disadvantages. If the rate of change is high, the probability
that the disadvantages outweigh the advantages is higher as well. For
code there is a wide agreement, that redundancy is bad. I would argue,
that most of the arguments, that lead to this conclusion, also apply to
comments.

Now the possible explanation:
I think the main problem with the assertion that code should be
documented in all circumstances is that there is an implicit assumption,
namely that there are infinite ressources available. However,
documentation does not come for free.

Ask yourself the following question: You have spent six hours writing
some code and you have two hours left. What should you do in this two
hours to make your code better? Write additional tests, refactor your
code to make it more understandable, or document it?

In almost all cases, I'd rather go for the first two options. And I'd
rather have other people do so as well. I *don't* want people to spend
their time writing comments when there are still possibilities for
refactoring and writing tests!

I will admit that in theory a well written class cannot become worse to
understand by adding a well written comment, quite the contrary. But in
practice there are always tradeoffs. And I think the fact that the rate
of comments is lower than you seem to think it should be is best
explained by the fact that there are more important things than
documentation.

Now, I know that there *are* developers who don't want to write comments
because they *are* lazy. I know that my arguments might be abused by
them to get away with being lazy. I cannot do anything but state that
this is not my intention!

No offence meant!

- Bernhard