Path: utzoo!utgpu!jarvis.csri.toronto.edu!torsqnt!tmsoft!masnet!canremote!decot@hpisod2.hp.com
From: decot@hpisod2.hp.com@canremote.uucp (decot@hpisod2.HP.COM)
Newsgroups: comp.misc
Subject: Re: Re: Coding standards (was
Message-ID: <89122504120994@masnet.uucp>
Date: 21 Dec 89 05:03:00 GMT
Organization: Canada Remote Systems Limited, Mississauga, ON, Canada
Lines: 46

From: decot@hpisod2.HP.COM (Dave Decot)
Subj: Re: Coding standards (was Re: Programmer productivity)
Orga: Hewlett Packard, Cupertino

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

---
 * Via MaSNet/HST96/HST144/V32 - UN Misc. Computer Topics
 * Via Usenet Newsgroup comp.misc