Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!ucbvax!agate!hughes@math.Berkeley.EDU
From: hughes@math.Berkeley.EDU (eric hughes)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <20233@agate.BERKELEY.EDU>
Date: 11 Feb 89 02:27:37 GMT
References: <1813@goofy.megatest.UUCP>
Sender: usenet@agate.BERKELEY.EDU
Reply-To: hughes@math.Berkeley.EDU (eric hughes)
Organization: UCB Mathematics Department
Lines: 74
In-reply-to: djones@megatest.UUCP (Dave Jones)

In article <1813@goofy.megatest.UUCP>, djones@megatest (Dave Jones) writes:
>In my opinion, the most important parts of a program to document
>are the structure-declarations and the variable-declarations.
>You document what the fields and variables "mean" in terms of
>invariants.

To add to this, I will often explicitly make a comment that a
certain variable is "valid," that is, it satisfies all the
invariants of its type, as well as ones specific to the variable.
Then I am very careful not to use a variable which is not shown
to be valid.  If part of it is, I'll declare that part valid and
use it.  This technique has prevented many stupid bugs.

>					       If you do that, and
>if the code is well structured, documenting an algorithm is usually
>(but not always) unnecessary. Usually it is obvious how the algorithm
>will go about the process of reestablishing a broken invariant.

I always document an algorithm, not matter how silly.  This has
helped me avoid what I term "typo bugs," things I meant to do
but forgot.

>		  If the algorithm is not tricky, the WHAT
>will make the HOW clear enough.   

Yes, a good statement of the preconditions and postconditions to a
function can eliminate most procedural comments. (e.g. now we need to
do this, now that.)  Rather than use a procedural comment before I do
something, I will use an assertion comment about the program state
afterwards.  This is more useful to me, since it is more detailed and
states exactly what just happened, not what I intended it to do.  For
some reason, I find it easier to objectively look at an assertion than
an intention.

>				   Comments which assert
>the obvious are just clutter, worse than nothing.

I have found that my grasp on the obvious is not what I
think it is. :-)  My rule of thumb is not to comment anything
which is implicit in the syntax of a statement, but I will 
sometimes comment on the semantics (especially in the case of
function calls) and always on the pragmatics (what effect it
has).

I had a friend once who was taking an assembly language class
where the teacher required every program line to be commented.
He wrote a filter to translate every instruction into it English
equivalent and present it as a comment on that line.

	LOAD AX, 1		; load the register AX with the value 1

The teacher was satisfied and the student got good scores
on his programs.  This is the kind of syntax-based comment I
avoid.

In a related issue, I have found that program correctness techniques
are a good way of documenting code.  Not only to they allow you to
know that what you are doing is correct, but, more importantly, they
are the most concise way of stating exactly what the program does.
It is elegant to my mind because it is as simple as possible, but
no simpler.

Every loop gets both a loop invariant and a bound function in a 
header before it starts.  At the end, the termination conditions
are stated explicitly.  From that, I separately assert the desired
postcondition for the loop.  I have found this accurately describes
both what the loop does and the outline of how it works.

Now I would like some engineering tools with which I could check my
correctness proofs, but since none exist (to my knowledge), I have
found that conscientious commenting is acceptable.

Eric Hughes
hughes@math.berkeley.edu   ucbvax!math!hughes