Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Posting-Version: version B 2.10 beta 3/9/83; site callan.UUCP
Path: utzoo!watmath!clyde!burl!ulysses!mhuxl!houxm!houxz!vax135!cornell!uw-beaver!tektronix!hplabs!sdcrdcf!trwrb!scgvaxd!wlbr!callan!geoff
From: geoff@callan.UUCP (Geoff Kuenning)
Newsgroups: net.unix
Subject: Re: Commentary
Message-ID: <198@callan.UUCP>
Date: Fri, 20-Jul-84 22:05:20 EDT
Article-I.D.: callan.198
Posted: Fri Jul 20 22:05:20 1984
Date-Received: Tue, 24-Jul-84 03:36:41 EDT
References: <2967@rabbit.UUCP>
Organization: Callan Data Systems, Westlake Village, CA
Lines: 53

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