Path: utzoo!mnetor!uunet!ncc!alberta!cdshaw
From: cdshaw@alberta.UUCP (Chris Shaw)
Newsgroups: comp.software-eng
Subject: Re: American Programmer
Message-ID: <1201@pembina.UUCP>
Date: 7 Apr 88 21:39:14 GMT
References: <87@studsys.mu.edu> <3850007@wdl1.UUCP>
Reply-To: cdshaw@pembina.UUCP (Chris Shaw)
Organization: U. of Alberta, Edmonton, Alberta, Canada
Lines: 37

In article <3850007@wdl1.UUCP> rhj@wdl1.UUCP (Bob Jones) writes:
>My basic rule of thumb is:
>
>	I always maintain a healthy paranoia of having to maintain 
>	my own code. 
>
>Healthy comments make this paranoia manageable.
>
>Bob Jones
>Ford Aerospace

Very true. Actually, one of my more satisfying recent software writing
experiences came last year while I was consulting. The firm I was consulted
by had a very poorly documented piece of hardware that needed a real-time
software driver. There followed a very frustrating round of interviews
with somewhat Un-professional engineers regarding the true features of
the botch I was to write software for. This process was eventually completed,
and I spent the next while writing the design document.

I then spent what seemed like three minutes coding it up. I even managed
to discover an obscure IO bug, which I spent an inordinate amount of time
working around. It's one of those interesting things. Documentation is easy
throw away, but code is hard (psychologically) to pitch. If you settle
all the design issues with text only, you will probably end up with a better
design. I imagine it's because text is a lot easier to read (and therefore
critique) than is code.

The major point being that with a solid external document, maintenance is
likely to be very straightforward. Of course, my motivation for thoroughness
was a desire to never hear from these people again, unless they had another
contract for me. As for comments, I don't recall. These people had a very
nice standard for documenting variables and so on, so I followed that fairly
carefully.
-- 
Chris Shaw    cdshaw@alberta.UUCP (via watmath, ihnp4 or ubc-vision)
University of Alberta
CatchPhrase: Bogus as HELL !