Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!sq!msb
From: msb@sq.UUCP
Newsgroups: comp.lang.c
Subject: Re: documentation standards........
Message-ID: <1987Oct15.212022.20550@sq.uucp>
Date: Thu, 15-Oct-87 21:20:22 EDT
Article-I.D.: sq.1987Oct15.212022.20550
Posted: Thu Oct 15 21:20:22 1987
Date-Received: Sat, 17-Oct-87 07:07:48 EDT
References: <9710@brl-adm.ARPA> <1596@megatest.UUCP>
Reply-To: msb@sq.UUCP (Mark Brader)
Organization: SoftQuad Inc., Toronto
Lines: 40
Checksum: 08708

I mailed a long response to the person who posted that "Coding Standard
for C Programs", but I think it may be worthwhile to also post a summary
of my major points.

1.  It isn't a coding standard for C programs.  It's a coding standard for
    modular programs in general, partly adapted for C.  For instance, it
    doesn't specify anything about how to align enum or struct declarations.
    (The Indian Hill Style Sheet does.)  Little is said about types.

2.  The examples show several signs that they were not written by a C
    programmer; for instance, using a while-loop instead of

	for (iterations = 0; upper - lower > epsilon; iterations++)

    and the use of scanf() as if it read an input *line*.

3.  The examples also show bad modularization, as the same function is
    used to compute and print a value, and unnecessary complexities,
    like assigning a variable to another with a different name because
    something else is going to be done to it now.

    The last function, with 31 lines of comment and code, should have been:

	#define sign(x) ((x) >= 0)

4.  The fill-in-the-blank header comments are hard to read and hard to
    maintain, especially the "called by" entry.  Some other rules are
    similarly well-intentioned-but-too-strict; for instance, there are
    other stereotyped uses that call for 1-letter variable names besides
    loop indexing.

5.  Despite these and other points, such a standard is still better than
    no standard, especially in a student environment where people may have
    to be weaned off all-variables-1-letter and goto-spaghetti.  But I would
    recommend The Elements of Programming Style above all.

Mark Brader		"It's important not to let the structure of the
Toronto			code determine the functionality of the program ...
utzoo!sq!msb		The desired functionality should be predetermined
msb@sq.com		before the code writing is done."	-- Dave Sill