Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!purdue!rjh
From: rjh@cs.purdue.EDU (Bob Hathaway)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <6066@medusa.cs.purdue.edu>
Date: 17 Feb 89 23:30:19 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Sender: news@cs.purdue.EDU
Reply-To: rjh@cs.purdue.edu (Bob Hathaway)
Organization: Department of Computer Science, Purdue University
Lines: 65


>                      Also, no one wants to take the time to rewrite
>their code into English; it's a boring, tedious job, and when it comes

This seems to go backwards.  Programmers should first design
their software then implement it.  You seem to be advocating 
implementation then design.  The descriptive algorithm should 
come first, then the code.  If the algorithm can be coded in a
truly self descriptive form no comments will be necessary but in
instances where the design and implementation are not the same,
comments help.

>Will requiring Joe Programmer to write more comments fix the situation?
>No.  Joe Programmer will find a way to keep his comment writing to a
>minimum, even if the code or organization of modules has to suffer for
>it.

True, but requiring Joe Programmer to design his software first will help,
and the design can be included in the comments.

>This is the solution:  code should be self-documenting.  But,
>self-documenting is not the same as commenting!  When I change a line
>of code, my documentation should reflect that change automagically.  I
>don't get this with comments, and because of it, the only comments I
>rely on are my own personal ones.

I've always believed in self-documenting code and used this excuse
to avoid commenting until I graded a systems programming course
about a year ago.  The programs which had long procedures, few comments,
and weren't self documenting (*to me* at least) were the worst.  Trying to
work with these programs in a professional environment would have been a
nightmare.  The self-documented programs which kept their procedures
small and abstracted a single function were by far the best but
comments were still necessary.  Uncommented programs take several times
longer to read and understand than commented ones.  After my experience 
grading and after working with several large programs my conclusion is that
well commented, self-documenting code is by far the best.  Also, forcing 
an a-priori design and including this design in comments will not only
produce higher quality and better designed programs but programs which are
more easily understood since the structure of the software is documented.

>intentions of what I was programming.  We need to improve our
>programming languages, not increase the quantity of our commenting.

I agree entirely and advocate languages which allow direct expression of
algorithms and design.  But since current languages are approaching that
point and are not yet there, commenting is still necessary.

>There are many instances on where poorly documented code is "worse than
>nothing"; most notably, when the comments are WRONG!  It has happened
>too many times that someone reads the comments on how the routine is
>"supposed to" work, makes a change, and finds out that the
>implementation is totally different than the comments.  I wonder how
>many lost man-years in software maintenance can be attributed to this.

I think the poorly designed, poorly documented systems have caused most
of the trouble, not out-of-date commenting.   Just follow the convention
that when code is updated so are the comments.  The benefits of a well
commented design far outweigh the costs.  Well documented code is easy
to understand and modifications to the software can be done in terms of
the higher-level design.  Since the design is directly implemented in the
code, corresponding changes should be easy.

Bob Hathaway
rjh@purdue.edu