Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!husc6!bbn!diamond.bbn.com!mlandau
From: mlandau@bbn.com (Matt Landau)
Newsgroups: comp.lang.c
Subject: Re: documentation standards for C
Message-ID: <9232@slate.BBN.COM>
Date: Mon, 28-Sep-87 19:30:55 EDT
Article-I.D.: slate.9232
Posted: Mon Sep 28 19:30:55 1987
Date-Received: Wed, 30-Sep-87 00:39:15 EDT
References: <9500@brl-adm.ARPA> <343@taux01.UUCP>
Reply-To: mlandau@bbn.com (Matt Landau)
Distribution: world
Organization: BBN Laboratories Incorporated, Cambridge, MA
Lines: 29
Summary: Stop before it's too late!

Can we please try to head off this discussion before it's too late?
Questions about programming style and standards are fine, but it's clear this
conversation thread is on the verge of turning into yet another endless
series of comments on why my style for indentation and whitespace is better
than yours.

Since this is the canonical religious issue in C programming, why don't we
all just agree not to wage a Holy War :-)

For those who really are concerned about coding standards, I'll point out
that my project here at BBN has a set, and we try to adhere to it.  It says
as little as possible about indentation and whitespace beyond arguing for
some consistency so that everyone's code is readable and editable by everyone
else.  It doesn't matter what the style is, as long as everyone agrees to
stick to it.

The things we really did have to specify included rules about relying on long
symbol names (don't), byte or word ordering (don't, or at least provide
ifdefs for all reasonable cases), or Rieser preprocessor tricks (don't),
including structured comments at the beginning of source files and functions
(which allow us to use trivial tools like grep to build indexes of what
functions are defined in a source file, etc.), conventions for preventing
multiple inclusion of .h files, and so on.

If your life would be significantly enriched by seeing a copy of this
document, send me mail and I'll see what I can do :-)
--
 Matt Landau			Standard are industry's way of 
 mlandau@bbn.com			      codifying obsolescence.