Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!seismo!sundc!hqda-ai!cos!smith
From: smith@COS.COM (Steve Smith)
Newsgroups: comp.lang.c
Subject: Re: Writing readable code
Message-ID: <368@cos.COM>
Date: Thu, 16-Jul-87 13:49:10 EDT
Article-I.D.: cos.368
Posted: Thu Jul 16 13:49:10 1987
Date-Received: Sat, 18-Jul-87 08:15:50 EDT
References: <598@nonvon.UUCP> <2365@bunker.UUCP>
Reply-To: smith@cos.UUCP (Steve Smith)
Organization: Corporation for Open Systems, McLean, VA
Lines: 52

In article <2365@bunker.UUCP> garys@bunker.UUCP (Gary M. Samuelson) writes:

>...  Some of us are actually not permitted
>to "do it right."
> ...
>"Yes, documentation is important, but so-and-so customer is screaming
>for such-and-such a feature, so we can't schedule time to write anything
>but code."

Amen!!

Gary's points are well taken.  Besides managerial incompitence, there
is another problem to deal with, and that is the (all kowtow)
CUSTOMER.  As a former employee of a Beltway Bandit (suburban
Washington DC defense contractor) whose only desire is to remain
nameless, I had to constantly deal with managers who swore up and down
that "the Customer needs first rate doccumentation".  Very nice.
Except that "doccumentation" meant "doccumentation to MIL-STD-1679"
AND NOTHING ELSE.

For those of you who are mercifully unaware of this monstrosity, it
was written in the early '70's to standardize the doccumentation of
COBOL programs.  The doccumentation has two sections, variables and
code.  All data structures, variables, and subroutines must be
treated as globals.  Variables are described by little pictures
telling what the bits mean.  Defining structures in terms of other
structures is forbidden.  There is no way to represent any form of
concurrency or multitasking.  This awful stuff must be written and
approved by the Customer before you can do any coding at all
(including proof-of-concept).  Once it is approved, it cannot be
changed.

This may be OK for COBOL (I count COBOL as an unnatural act, anyway).
For FORTRAN or C, it is just marginal.  For C++, PASCAL, ADA, or any
AI language, it is impossible.

The effect of all this is to push the code away from a modular, object
oriented design toward "structured spaghetti code".  I don't care if a
program doesn't use GOTOs, if it has hundreds of teeny little modules
all calling each other with no apparent large scale structure, it's
going to be hard to figure out.  If you DO try to maintain some high
level structure through "informal design doccuments" (specifically
forbidden by most contracts) you confuse the bejesus out of everybody,
because you now have two sets of contradictory doccumentation.

The net effect of this is that Management and the Customer THINK that
they are insuring good doccumentation, while what happens is the
reverse.  After any maintenence activity at all, any structure that
might have existed is completely trashed.

Faugh!  Anybody who has ever done program maintenence knows what s/he
needs.  The exact format is unimportant.