Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10.1 6/24/83; site fortune.UUCP
Path: utzoo!linus!decvax!harpo!ihnp4!fortune!phipps
From: phipps@fortune.UUCP (Clay Phipps)
Newsgroups: net.lang
Subject: Re: Forced Commenting
Message-ID: <2185@fortune.UUCP>
Date: Thu, 5-Jan-84 21:50:09 EST
Article-I.D.: fortune.2185
Posted: Thu Jan  5 21:50:09 1984
Date-Received: Sat, 7-Jan-84 01:46:29 EST
References: <2179@fortune.UUCP>
Organization: Fortune Systems, Redwood City, CA
Lines: 43

-------------------------------
Expending implementation effort or invoking the wrath of the local
standards czar or class instructor to force commenting is a total waste 
of time.  What will be produced for a sequence of code like this
    
    j := 0;
    ... 
    j := (j + 1) mod n;

by an unwilling, unconscientious, or misguided commmenter (commentator ?) 
will be something like this
    
    j := 0;              {zero out j}
    ... 
    j := (j + 1) mod n;  {add 1 to j}

The above only told you WHAT was being done,
which you could get from reading the statements without their comments.
With an example like that, you'll have a difficult time
convincing students, employees, or the neighborhood kid hacker
that commentary in programs is important or even useful.
The thing that is really needed for these same source statements 
is some information as to WHY things are being done.
If this code were being used to implement a queue, 
then I would want comments like these
    
    j := 0;              {select initial element of queue}
    ... 
    j := (j + 1) mod n;  {advance to next element in queue}

Now the reader should be able to figure out that the queue is circular.
The code itself is not really readable, per se, 
but the comments above bear the entire burden that should really be shared
by judicious selection of symbolic names and appropriate commentary.
Anyone who has to maintain or enhance the code is better off
with names more like "QElemIndex" and "QElemLimit" than "j" and "n".

-- Clay Phipps

-- 
   {allegra,amd70,cbosgd,dsd,floyd,harpo,hollywood,hpda,ihnp4,
    magic,megatest,nsc,oliveb,sri-unix,twg,varian,VisiA,wdl1}
   !fortune!phipps