[net.lang] Forced Commenting

wapd@houxj.UUCP (Bill Dietrich) (01/04/84)

Out of pure curiosity :

	Does anyone know of a language (or compiler, interpreter
or assembler) that REQUIRES comments ?  To force "good" documentation,
sort of ?

	For example, one might want to require a block comment at
the beginning of each function.  Or force a comment on every line
of assembly language programs (especially useful for an assembly
language course).

	Another twist is to require a comment on every line that is
complex, by some measure (numbers of characters, number of operators,
bizarre instructions, data in text section, etc).

				Bill Dietrich
				houxj!wapd

liz@umcp-cs.UUCP (01/04/84)

Yes, I have heard of a compiler that had forced commenting.  I
think it was our local PL/1 compiler -- the PLUM compiler (PL/1
Univ of Maryland).  It simply required 10% of the lines to be
comments or to contain comments.  If they didn't, you got some kind
of warning message.

				-Liz Allen
-- 
Univ of Maryland, College Park MD	
Usenet:   ...!seismo!umcp-cs!liz
Arpanet:  liz%umcp-cs@CSNet-Relay

ken@turtleva.UUCP (Ken Turkowski) (01/05/84)

Cobol is so verbose, it forces comments.
[All flames should be sent to /dev/ibm].

mckeeman@wivax.UUCP (01/05/84)

Teaching systems have tried enforcing certain style
requirements.  I once had a no-paragraph-punisher for PL/I,
and a comment counter.  The former was quite interesting.
Within two weeks, I could have turned it off, NOBODY
violated the conventions after that.  The comment counter
was less successful.  What it did was force the student to
write comments, so that the grader could evaluate them.  It
stopped the /* increment i */ kind of comments.  My rule
was a comment for every procedure, begin and do.  What I
mainly learned was that no simple rule would do, and spent
a lot of time defending the comment counter algorithm,
instead of evaluating the quality of the comments.
Incidentally, failure to pass the style checks prevented
execution...

It is my present opinion that a static analyzer, style
analyzer should precede compilation, and be passed before
compilation is allowed.  Thus the program {x=1; x=2} could
not be compiled because x is not used after it is set.
Fortunately I am not teaching programming right now...

jr@fortune.UUCP (John A. Rogers) (01/06/84)

I used to use an assembler (ASSIST), which had an option to require comments.
(ASSIST was written for the IBM 360/370 series, by the University of
Pennsylvania, if I remember correctly).  You could install the assembler on
the system, and define what percentage of the instructions should have non-
blank comments.  We didn't have it installed with that option, so I don't know
how smart it was, and I don't have the documentation any more.

I'm not sure that just checking for the existence of comments is very useful...
For instance, I've seen code from IBM (e.g. parts of OS, HASP, and an
air-traffic control system), where lots of lines have comments, but they tend
to be of the form "PTF12345-99"...  I.e., whenever they change the code, they
"gang-punch" (or whatever) a code number which indicates why the fix was made
(where PTF stands for "Program Temporary Fix").  This is a comment, but it's
not what I would call a "useful" comment.  I'd like to see the PTF number (or
whatever), but I'd also like to see DESCRIPTIVE comments, and I don't know how
you'd write a program to check for them.

I hope this helps...
-- 
John Rogers - CompuServe: 70140,213 - UUCP: fortune!jr - MCI Mail: jrhpp

robison@eosp1.UUCP (Tobias D. Robison) (01/06/84)

I don't know of a compiler or assembler that forces comments,
but I'm not sure it would do much good.  Haven't you seen
comments like these:

C	Now multiply total times percent:
	AMOUNT = TOTAL * PERCEN

C	Check whether switch is nonzero:
	IF SWITCH .NE. 0 goto 1200

C	open the "squmxk" file:
	...and so on.

Or, my favorite in assembly language comment:

	ADD R1,R2	;add register 2 to register 1

Good comments are written by people who know what they are doing and
want to do it.
				  - Toby Robison
			          decvax!ittvax!eosp1!robison
				  or:   allegra!eosp1!robison
				  (maybe: princeton!eosp1!robison)

phipps@fortune.UUCP (Clay Phipps) (01/06/84)

-------------------------------
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

tjt@kobold.UUCP (T.J.Teixeira) (01/06/84)

wivax!mckeeman says:

	Incidentally, failure to pass the style checks prevented
	execution...
...

	Fortunately I am not teaching programming right now...

Actually, I think it's more fortunate you're not writing the Unix C
compiler now! :->

-- 
	Tom Teixeira,  Massachusetts Computer Corporation.  Westford MA
	...!{ihnp4,harpo,decvax,ucbcad,tektronix}!masscomp!tjt   (617) 692-6200

smh@mit-eddie.UUCP (Steven M. Haflich) (01/06/84)

A wonderful notion!  But how do we convince yacc and lex properly to
document generated code and tables?  While we're at it, let's have GM
build automobiles that *can't* be driven faster than 55 MPH.  :-)

Seriously, I fuzzily remember from working at IBM in the 60 that there
were standards for documentation of assembly code:  basically, every
code line should bear a comment.  Needless to say, such a standard
cannot guarantee comments which are useful.

ram@pyuxbb.UUCP (R Allan Muller) (01/09/84)

I find that a printed copy of a program is essential for maintaining large
software systems.  A visual editor gives a good view of a small portion of a
routine; however, it does not show a whole routine at one glance.

I believe that programs should be formatted for presentation on paper.  Comments
can then be placed in line or set off by white space as appropriate.  Programs
that are formatted for a screen tend to be too compact for my taste; needed
documentation is eliminated to allow the program to fit on a screen.

andree@uokvax.UUCP (01/11/84)

#R:houxj:-31900:uokvax:9000016:000:1049
uokvax!andree    Jan  9 21:02:00 1984

Yes, I have noticed the problem of screens (and printers) being to
narrow/short/SMALL. The solution is not in the hardware (especially
printers), nor in the languages, but in the display software.

My solution to this problem is to format code for an 80 line printer/terminal
(I too use an MX-80 for printing), with blank lines and comments interspersed
fairly freely. If something won't fit on the screen, I tend to bend it a
little - or better yet, try to reorganize the code. Things work great on
printers.

Then, to edit the code, I use (semi-)smart software. Editors that will let
me split the screen are a *MUST*, so I can look at a structure/define/comment
while writing the code that uses it/them. If the definition is in another file,
this feature is even more important.

Better yet are truly smart editors, that will let me elide pieces of the text.
Things like all things nested below level n, or all in-line comments, or all
comments, etc. I can chase down further references for anyone that's
interested. Or ask in net.cog-eng.

	<mike

saj@iuvax.UUCP (02/15/84)

#R:houxj:-31900:iuvax:11800009:000:977
iuvax!apratt    Jan  8 00:47:00 1984

One thing which has often stymied my attempts at commenting is the fact that
screens and printers are 80 columns wide (MX-80s, anyway).  With that
limitation, deeply nested structures have no room at the end of the line for
comments, and no good place to put one (the line above? the line below?).
Another limitation is 24-line screens. With most editors, this leaves (at most)
23 lines of the program visible at one time, and for that reason blank lines
need to be scarce (especially in complex structures where you want to see as
much as possible). On the other hand, complex structures are where blank lines
are MOST helpful on a printout, with plenty of blank-line-delimited comments.
	Which way do you go with it? Depends mostly on the availability of
printouts. If they're quick and cheap, use that right margin (and beyond)
for all it's worth. Otherwise, program for the screen.

	Has anybody else noticed this problem?

						-- Allan Pratt
					...ihnp4!iuvax!apratt

decot@cwruecmp.UUCP (Dave Decot) (02/16/84)

If a function or procedure gets too long, or too deeply nested to fit in
a screenful, take some of the deeper code and move it to a separate procedure
or function.  This will leave more room for comments and blank lines, and if
the new modules are selected well, makes the program even easier to understand.

If a data structure initialization gets too long or complicated to fit on one
screen, find some way to modularize it, or read it in from a separate file.

Dave Decot		 "Programmers are people, too."
decvax!cwruecmp!decot    (Decot.Case@rand-relay)

sdo@u1100a.UUCP (Scott Orshan) (02/17/84)

Putting comments on deeply nested code is only a problem if the comments
are on the right.  There's no reason the comment can't precede the code.

e.g.

/* Print "hello world" message */                    printf("hello world\n");

			Scott Orshan
			Bell Communications Research
			Piscataway
			201-981-3064
			ihnp4!u1100a!sdo

edhall@randvax.ARPA (Ed Hall) (02/18/84)

----------------------------------
I'm a great believer in block comments in front of every procedure
definition, and a minimum number of line-by-line comments in the
code.  I assume that the person reading the code knows the language,
and so reserve line comments for `tricky' code only (which I try to
avoid).  If the algorithm needs explaining, put it in the block
comment.  If that comment is too long, it's a sure sign the procedure
is doing too much, and should be divided into sub-procedures.

Forced commenting?  The ultimate in silliness.  It's quality, not
quantity you want.  If the code is badly written, commenting doesn't
make it any better.

		-Ed Hall
		decvax!randvax!edhall   (UUCP)
		edhall@rand-unix        (ARPA)

peters@cubsvax.UUCP (02/20/84)

I used to code in APL, whose conciseness has two implications, one 
"good" and one "bad:"  On the good side, since a procedure that would take
ten lines in C would take a single line in APL, it was very rare that a
procedure was more than a screen (24 lines) long, and most were 5 -10 lines.
This made it very easy to look at a whole procedure at once and figure out
what it was doing -- hence tending to make prolific commenting less 
necessary.  On the other hand, there was so much in a single line that
it was sometimes hard to see what was being done on a very detailed level,
which tended to make comments *more* necessary.  In most languages the
thing to be concerned about is "missing the forest for the trees."  In
APL, I used to worry more about "missing the trees for the forest."

I usually had a few block 
comment lines at the beginning of a procedure, and more only when necessary, 
or when the procedure was very long.  Then I had a routine which would
go through a workspace and print only function headers and comment lines.
Printing these out for all the routines in a workspace gave a wonderful 
synoptic view of what the different functions did.

{philabs,cmcl2!rocky2}!cubsvax!peters            Peter S. Shenkin 
Dept of Biol. Sci.;  Columbia Univ.;  New York, N. Y.  10027;  212-280-5517

jas@druxy.UUCP (ShanklandJA) (02/21/84)

One more semi-pertinent comment on comments:

It has been my experience that if you comment in detail the function of
each data structure ("data structure" here includes all storage objects,
such as scalars, arrays, structures, etc.) and their interactions
at the head of the function or module that uses the data structure,
two things happen:

(1)  You are much more likely to write correct code (I have found "bugs"
     writing out the comment on a data structure before writing a line
     of code!).

(2)  Commenting the *statements* becomes almost entirely unnecessary;
     to a reader who understands the data structures, the actions of
     virtually all the statements become obvious.

Give it a try!

Jim Shankland
..!ihnp4!druxy!jas

thomas@utah-gr.UUCP (Spencer W. Thomas) (02/28/84)

My solution to limited terminal width vs comments is to put long
comments before the block of code to which they apply.  The code block
then usually has NO comments, but that's ok, the entire action was
explained above.  Makes the comment more readable, too.  Also forces me
to write meaningful comments (no "Increment a" type comments).

=Spencer