Path: utzoo!utgpu!jarvis.csri.toronto.edu!cs.utexas.edu!sun-barr!decwrl!ucbvax!hplabs!hpda!hpcupt1!hpisod2!decot
From: decot@hpisod2.HP.COM (Dave Decot)
Newsgroups: comp.misc
Subject: Re: Re: Coding standards (was Re: Programmer productivity)
Message-ID: <4400007@hpisod2.HP.COM>
Date: 9 Dec 89 00:09:38 GMT
References: <9157@hoptoad.uucp>
Organization: Hewlett Packard, Cupertino
Lines: 34

The questions I want answered by comments are:

	What do the possible values of this variable or type represent,
	within the user's abstraction?

    and

	What does this code expect, and what does it assume, about the
	values of its arguments and surrounding variables?

    and

	What, abstractly, does this code guarantee when it's done?

For instance,

	int status;	/* GOOD if the laser hit the target, BAD if not */

	status = zap(plane2);	/* try to blast the enemy plane */

	if (status == GOOD)	/* the airplane was successfully destroyed */
	{
	    ++k;			/* bump the death toll */
	    kill(SIGUSR1, pid2);	/* notify the air traffic controller */
	}

I don't care what bits you're twiddling, I want to know what it's supposed
to be for, and what it means abstractly.

The interesting thing about comments like this is you can grab them straight
out of a specification document.  >> HINT!!! <<

Dave Decot
hpda!decot