Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!husc6!mit-eddie!uw-beaver!teknowledge-vaxc!sri-unix!amdahl!dlb!megatest!djones
From: djones@megatest.UUCP (Dave Jones)
Newsgroups: comp.lang.c
Subject: Re: documentation standards........
Message-ID: <1596@megatest.UUCP>
Date: Mon, 12-Oct-87 21:31:21 EDT
Article-I.D.: megatest.1596
Posted: Mon Oct 12 21:31:21 1987
Date-Received: Wed, 14-Oct-87 06:49:37 EDT
References: <9710@brl-adm.ARPA>
Organization: Megatest Corporation, San Jose, Ca
Lines: 52


You asked for comments.

This was one of the best documents I have seen on C programming standards.
I would like to add just a couple of suggestions.

1. Emphasize the documentation of variables and data-structures rather
than algorithms.  With few exceptions, algorithms should be so simple
as to require no comment.  If you are writing algorithms which require
documentation, you probably should simplify them.  There are exceptions
of course.  If you have taken an algorithm from a book, give a reference.

I have had a great deal of practice (and a great deal of frustration)
maintaining old code.  The trick to figuring out what the code does is
to figure out what the data represent.  In the parlance, "What are the
invariant relations?"  That is to say, what relationships between the
various data must be maintained, except in the "critical regions" which
manipulate the data?  If you know what the data represent, you know
what it is that the code MUST do (or SHOULD do), regardless of how
obscurely the original programmer coded the algorithms.

Internal documentation of algorithms is usually just distracting.
"Update the lset counter and remove entry from the exception table"
means absolutely nothing if you don't know what the lset counter represents,
or when entries belong in the exception table.  If you know those things,
the comment is extraneous.

Requiring that the variables be described in a header introduces the
possibility of the header and the code getting out of synch, and
creates busy-work.  Require instead that the variables be documented where 
they are declared.

2. Alphabetical organization makes no sense at all.  Organization by
form is little better.  One constant head-ache in the UNIX invironment
is caused by the fact that .h files must be separated from the
object files which they represent.  Keep related files together.  
I recommend that the source code be organized by data-structure.
For each related set of data-structure definitions, have two .h files:
one which is used by the routines which access the data-structures directly,
another for the routines which will access them only indirectly by means
of the first group of routines.  Put all the direct access routines in
one file.  If that file grows too large for efficient compilation,
put the routines in separate files in their own directory, or give them
names which clearly indicate that they (and only they) belong to the
direct-access .h file.  Example naming convention:

	hash_table.h   /* .h file describing routines which implement 
	                *  hash-tables, and opaque handles for hash-tables
		        */
	hash_table.i.h  /* .h used by the hash-table routines (only) */
	hash_table.create.c  /* One source file */
	hash_table.update.c  /* another. */