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.