Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!utgpu!water!watmath!clyde!cbosgd!ihnp4!ptsfa!ames!hao!husc6!cmcl2!brl-adm!brl-smoke!gwyn
From: gwyn@brl-smoke.UUCP
Newsgroups: comp.lang.c
Subject: Re: Writing readable code
Message-ID: <6087@brl-smoke.ARPA>
Date: Thu, 9-Jul-87 01:28:27 EDT
Article-I.D.: brl-smok.6087
Posted: Thu Jul  9 01:28:27 1987
Date-Received: Sat, 11-Jul-87 16:48:26 EDT
References: <598@nonvon.UUCP>
Reply-To: gwyn@brl.arpa (Doug Gwyn (VLD/VMB) )
Organization: Ballistic Research Lab (BRL), APG, MD.
Lines: 28

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.  You are quite correct in remarking that much code
available in the UNIX community is not very maintainable, with lack of
documentation being a primary factor.  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.  BWK's "pic" particularly
comes to mind as a very useful tool that has some incredible nonportable
"quick hacks" that should have been fixed inside AT&T, not by me and others
who receive the code after forking over a lot of money.

Another solution might be for even the researchy types to exert care to
make their code high-quality and as portable as possible.  I've found that
it doesn't take much longer to produce quality code, and in the long run
EVEN FOR ONE'S PERSONAL USE it saves time to do so.  Many's the time when
I've thanked the DAG of past years for anticipating future maintenance
questions and providing helpful information in the original sources.

I haven't even mentioned structured software design methodology, which
inherently produces accurate, complete software documentation.  (UNIX
types tend to resist doing things in an organized manner.)