Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!seismo!ll-xn!ames!ptsfa!nonvon!mc68020
From: mc68020@nonvon.UUCP (mc68020)
Newsgroups: comp.lang.c
Subject: Re: Writing readable code
Message-ID: <598@nonvon.UUCP>
Date: Mon, 6-Jul-87 21:39:19 EDT
Article-I.D.: nonvon.598
Posted: Mon Jul  6 21:39:19 1987
Date-Received: Sat, 11-Jul-87 01:08:45 EDT
Organization: NONVON Systems Computer Research Group
Lines: 71


   I have been reading all the articles in this series on readable code.  I
have seen some thouroughly ridiculous and outrageous comments and suggestions,
fortunately more than outweighed by the rational, well though out comments
of a few of our resident experts.

   What bothers me, however, is that while all of this discussion about style,
readability and portability is educational and even, for the most part, 
enjoyable, I have seen not one mention of what I consider to be the single
most important element of well written, portable code (in *ANY* language,
not just C!).  That element is DOCUMENTATION.  COMMENTS.  

   It is all well and good for the expert C guru to casually dismiss this 
with the most common (and most heinously WRONG) argument "any programmer
good enough to work on this code should be able to figure out what it does."

   Sure, a good programmer needs to be able to analyze a piece of code.  This
does not by any means imply that *EVERY* piece of code written should enforce
such analysis through lack of proper documentation.  Such excuses are precisely
that, the excuses or rationalizations of lazy, arrogant programmers.

   The plain fact of the matter is that any program that is undocumented is
a poorly written program, I don't care *WHO* wrote it, how elegant the
executable code is, how beautiful the algorithms...without documentation,
the program is incomplete.

   As an example, there is a small C program included in the news 2.11
distribution, under the misc directory, named article.c.  I will not name
any names, but it was written by a very well known and highly respected
member of the UNIX/net community.  I am sure that the program does whatever
it does elegantly and efficiently.  Therein lies the rub:  What the ****
does the program do?  No documentation header, no comments saying:  this program
does XYZ.

   There are a few scattered comments in the code which are virtually useless
to anyone but a guru level programmer, and probably not of much value to them.

   This program should NOT have been included in the distribution.  What
for?  So I can take several hours to several days of my time analyzing it
to figure out what the **** it does?????  Of course, in all fairness, it is
almost as well documented as the news software itself.

    I *HATE* approaching the problem of porting some piece of code from 
mod.sources to my system, because in 98% of the cases, there is little or
no documentation included.

    It is *WONDERFUL* that someone took the time to write a piece of useful
code, and chose to share it with the rest of us.  Commendations and kudos
to the contributors!  I should think, however, that they would be ashamed
to place in the public domain incomplete, poorly written programs with
THEIR names on them! (by that I am referring the above harped upon issue
of undocumented programs being incomplete programs)

    Frankly, I see two major classes of people foisting this crap off on the
world:  those who are simply too lazy to do things correctly (probably far
and away the largest group), and those whose arrogance causes them to 
deliberate obfuscate.

    Yes, I accuse many of the experts, particularly the older experts,
of deliberately making their code difficult to read, and to understand.
I believe their attitude is something like: "*I* had to suffere through
poorly documented code, and no comments, so everyone else should too."

   I have had some experts say such things to me in so many words.  I say
to them, and to all of you, that such an attitude is anti-social, counter-
productive, rude, and downright vicious.  So far as I am concerned, if that
is your attitude, then KEEP your damned knowledge, because it is flawed,
just as you are flawed.

   My apologies for the long-widedness and slight flamage.  This is an issue
I take very personally.