From: utzoo!decvax!harpo!npois!cbosg!cbosgd!mark
Newsgroups: net.misc
Title: Re: Self-documenting code???? Shesh!
Article-I.D.: cbosgd.2356
Posted: Mon Jun 14 10:10:45 1982
Received: Tue Jun 15 05:41:13 1982
References: sdcsvax.2093

While it is certainly important to be able to read code, comments are
still crucial in programs of any size.  In practice, of course, most
programs are quite large.  When a change needs to be made, it's most
often a trivial change of a few lines.  The problem facing the person
who must make the change (usually not the author) is FINDING those
few lines that need to be changed.  Also, this person must figure out
enough of the conventions used in the program to be able to make the
change.  There are two ways to get this information out of the program:

(1) Read and understand the code.  Most of it is irrelavent, but must
    be read and understood to determine that it can be ignored.
(2) Read the comments.  Good, high level comments at the front of
    programs, modules, procedures, and chunks of code are much faster
    to read than code, and make it faster and easier to find the
    appropriate place in the code.

Of course, if the program fits on your CRT screen or on a page of line
printer output, it may be as fast to read the code as to read the
comments.  But how many programs are this simple?  The real problems
are with the huge software systems that nobody knows every line of code.