Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!yetti!geac!daveb From: daveb@geac.UUCP Newsgroups: comp.lang.c Subject: Re: documentation standards... Message-ID: <1655@geac.UUCP> Date: Wed, 21-Oct-87 14:26:11 EDT Article-I.D.: geac.1655 Posted: Wed Oct 21 14:26:11 1987 Date-Received: Sat, 24-Oct-87 11:56:25 EDT References: <9710@brl-adm.ARPA> <1596@megatest.UUCP> Reply-To: daveb@geac.UUCP (Dave Collier-Brown) Organization: The little blue rock next to that twinkly star. Lines: 76 Keywords: expectations In reference the discussion of documentation standards arising out of "Coding Standard for C Programs", I should like to point out that the proposed voluminious header comments are counter-productive. Point 1: I had the interesting (and unpleasant) experience some years ago to become involved in backing out of a set of mistaken decisions in a major project[1], and one of the things which a) caused the erroneous decisions to be believed, and b) caused them to be hard to change, was an enthusiasm toward documenting a design in full and complete detail (but without verification of the correctness of the design). The header comments used by this project were substantially identical to those proposed, and did contribute to the problem. I propose that such comments are suitable functions which can be shown to be complete and correct under verification, and that their use be restricted to the documentation of complete and correct functions for purposes of maintenance. (Yes, my tongue is in my cheek... I'll make a constructive suggestion later). Second Point: Repeating the declarations and uses of variables in the header separates the declaration and description unnecessarily, and breaks the "write once" rule[2]. It is far better to put the description as close to the declaration as possible. It would be even better if the _uses_ could be close to the declaration, but that can be approximated by writing small functions, a normal "good practice". Proposal: David Gries[3] suggests that one document the preconditions for successful completion of a function and its result. This is consistent with what I've seen in "well-written" c programs, so I'll through this out for consideration: /* * strchr -- find a character in a string. Returns a pointer * to the character or NULL. Requires a pointer to a * null-terminated string and a character in the range 0 * to 0xFF. Behavior out of these ranges is undefined. */ char * strchr(p,c) register char *p; /* The string to be searched. */ register int c; /* The thing to search for. */ { /* Precondition: */ while (condition) { loop } /* Postcondition: */ return p; } --dave (note the **brevity** of the header comment) c-b [1] Hinted at in "My Accordian's Stuffed Full of Paper", ACM SIGSOFT Software Engineering News, July 1984, p 58ff. [2] A practice which stems from the MIT/Bell/GE Multics project: Have only one copy of a datum, and refer to it from wherever it is needed, preferably via a published interface. For example, sys_info_$max_seg_size is a size constraint. The rule can also be applied to documentation... [3] Gries, David, "The Science of Programming", Springer-Verlag (I forget the date). -- David Collier-Brown. {mnetor|yetti|utgpu}!geac!daveb Geac Computers International Inc., | Computer Science loses its 350 Steelcase Road,Markham, Ontario, | memory (if not its mind) CANADA, L3R 1B3 (416) 475-0525 x3279 | every 6 months.