Commentary

[Geoff Kuenning]

Rob Pike (rabbit!rob) has successfully demonstrated that anyone
can set up a straw man and knock it down.  I won't repeat Rob's
deliberately noise-loaded posting, since all it contained was a lot
of specious lines to prove that his terminal has an asterisk key.
Following is Rob's original uncommented program and a suggested way
to code the same function with USEFUL comments.

Rob's original:

bltin() 
{

	Datum d;
	d = pop();
	d.val = (*(double (*)())*pc++)(d.val);
	push(d);
}

And a TRULY improved version:

typedef	double (*pfd_t) ();	/* Ptr to func returning double, to clarify */
				/* ..the C syntax below */

bltin()				/* Execute any built-in function */
{

	Datum scratch;

	scratch = pop ();	/* Get value to operate on */
/*
	Run the function pointed to by "pc" on the top-of-stack value
*/
	scratch.val = (*(pfd_t)(*pc++)) (scratch.val);
	push (scratch);		/* Store result */
}

Certainly, the sample routine is small enough that a good C programmer can
understand it, with or without comments, in a few minutes.  Rob's deliberately
obfuscatory "comments" are successful in making this a harder task.  But
well-written comments can turn those few minutes into a few seconds, which is
important when you are dealing with a 50- or 100-line routine that is part
of a very large program.

In passing, let me note that Kernighan & Plaugher have sufficiently
addressed the "i++; /* Increment i */" type of "comment" that Rob so
loaded his "example" with.  If he really thinks that that is what commenting
is all about, I suggest that he investigate some of his co-author's other
books.
-- 

	Geoff Kuenning
	Callan Data Systems
	...!ihnp4!wlbr!callan!geoff