Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!seismo!ut-sally!husc6!think!ames!ucbcad!ucbvax!ulysses!ggs
From: ggs@ulysses.homer.nj.att.com (Griff Smith)
Newsgroups: comp.lang.c
Subject: Re: Writing readable code
Message-ID: <2720@ulysses.homer.nj.att.com>
Date: Fri, 10-Jul-87 10:01:30 EDT
Article-I.D.: ulysses.2720
Posted: Fri Jul 10 10:01:30 1987
Date-Received: Sun, 12-Jul-87 11:53:22 EDT
References: <598@nonvon.UUCP> <6087@brl-smoke.ARPA>
Organization: AT&T Bell Laboratories, Murray Hill
Lines: 39

In article <6087@brl-smoke.ARPA>, gwyn@brl-smoke.UUCP writes:
> In article <598@nonvon.UUCP> mc68020@nonvon.UUCP (mc68020) writes:
> [stuff about insufficient comments]
> 
> I think the reason there hasn't been much discussion about code commenting
> is because the need for it is well understood and drummed into the heads
> of most CS students.

I hope the students you know of are the norm.  When I was teaching a class
the only thing that got their attention was an ultimatum: "If I can't
understand your program in ten minutes, your grade is no better than a C".

> Remember, however, that a lot of
> the original UNIX code was developed as "fast prototypes" by people who
> needed functions for their research projects, so that production quality
> was not an issue for them.  What is much harder to excuse is the fact that
> the code quality and documentation have not been much improved by the folks
> who package and commercially license it.  One wonders what their job is, if
> not to clean up the product before distribution.

Sigh...  My spies at Summit tell me that part of the clean-up consists of
removing all author names and all attempts at humor.  There is now a
company-wide "quality" campaign, however, so maybe some of it will surface.

A few years ago there was resistance to changing anything if it didn't
improve the benchmarks.  It took me two years to convince people that
a command with ten bugs in 500 lines of code was broken.  I kept getting
the comment that "there haven't been any complaints, so nobody must be
using the features that are broken".  I was also told that the required
feature proposals, design reviews and quality assurance documentation
would be too expensive.  I finally gave them a fixed version accompanied by
a feature verification script and got it accepted.

Good comments, Doug.  Second the motion about doing it right the first time.
-- 
Griff Smith	AT&T (Bell Laboratories), Murray Hill
Phone:		1-201-582-7736
UUCP:		{allegra|ihnp4}!ulysses!ggs
Internet:	ggs@ulysses.uucp