Class comments!?

Richard A. O'Keefe ok at cs.otago.ac.nz
Mon Oct 18 23:47:13 UTC 2004


Background:
    > Bernhard Pieber <bernhard at pieber.com> wrote:
    > 	- Comments are a form of redundancy.
I denied it, and gave my standard advice:
    > "Comments should tell the reader what s/he needs to know
    > that ISN'T there in the code."
Bernhard Pieber <bernhard at pieber.com> wrote:
	Point taken.  I wrote "Comments are a form of redundancy."  You
	are right that this statement is false.  Let me take it back.

	While I have definitely seen a lot of comments which are
	completely redundant, this is of course not true for all
	comments.  A lot of them are really helpful.
	
We've all seen comments that are even *worse* than redundant.
Here's one where I desperately needed to know what the code is meant
to do (and in fact I've asked on another mailing list):

	# add weights
	for i in range(attLen):
	    rel_matrix_inv[i][iu] = (rel_matrix_inv[i][i] * weights[i])

The comment says "ADD", the code says "MULTIPLY".  Even worse, the design
documentation says the weighting is applied to some other variables, not
to the diagonal of this matrix.

	I can and do completely agree with your statement.  I would be
	interested in your position about the negation:  "Comments
	should NOT duplicate things which are in the code."
	
I do love nice crisp definitions.  I hate fuzzy logic.  I despise
situational ethics.  And yet, ...  The sad fact is that "what the
reader needs to know" depends on who the reader is, and what is "in"
the code depends on the ability of the reader to extract the information
and the time the reader has to do this.  For example, sometimes it is
useful to write down an algorithm in a very high level language as a
comment for the code in a low level language like C.  You _could_ figure
out what the C code is for, but the very high level code makes it so much
quicker to figure out.  So I would say

    Comments should only duplicate things which are in the code if
    (1) they are correct and consistent with the code and
    (2) there is an expected readership of the code which needs
        this level of help.

	However, I must disagree with one thing: I do not consider the above -
	false - statement the heart of my argument. I consider this to be the
	economic argument: Given a finite amount of time, what is it best spent
	on to increase the understanding for the reader: Writing additional
	tests, refactor the code or write comments? I would be very interested
	in your thoughts about this.
	
My answer has to be a feeble wishy-washy "it depends, some times tests,
sometimes refactoring, sometimes comments."  Test cases are TEST cases.
If a test case acts as a good example, that's good luck, but we can't
rely on good luck.  And doesn't a test case deserve a comment to say
what abstract property it is supposed to test?

The topic of this thread is *class* comments.  	I generally find that
knowing what the class invariants are helps me a lot.  Looking at the
code can tell me that some property _happens_ to be preserved, but it
can't tell me that it is an important structural property.  (Especially
if, as often happens, there is a mistake in the code and some invariant
is _not_ preserved.)  Refactoring doesn't help; the information still
has to go _somewhere_.

I suppose it's a bit like the question "what's the best way to treat
a patient" with the answer "it depends on what's wrong with the patient".
If you have to clean up a component in order to make it easier to understand,
the best thing to do depends on why the component is hard to understand now.




More information about the Squeak-dev mailing list