Path: utzoo!utgpu!utstat!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!cs.utexas.edu!pp!cadillac!sigsun!lewis
From: lewis@sigsun.cad.mcc.com (Dave Lewis)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <782@cadillac.CAD.MCC.COM>
Date: 16 Feb 89 21:36:29 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Sender: news@cadillac.CAD.MCC.COM
Reply-To: lewis%cad@MCC.COM (Dave Lewis)
Organization: MCC VLSI-CAD Program, Austin, TX
Lines: 80

Here's my comments on your comments about comments!

>In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes:
>
>>Especially in the Unix/C world, the overwhelmingly vast majority of
>>programs are undercommented.  It's interesting that some aspects of
>>programming style, e.g. indentation, are fairly consistently applied,
>>while adequate documentation is the remote exception.

WHY is indentation almost universally used?  Because the payback to the
programmer is immediate and effective!

Why is adequate documentation a remote exception?  I don't think that
it's a question of correctness, although this is a demotivating factor.
Rather, I think that the typical comment does not convey any useful
information to the programmer later.  Indentation does, so it gets done.
>
>The question is:  Why?  From my point of view, good documentation in
>the form of comments is rare because there is NO WAY of guaranteeing
>that they are correct with respect to the code.  They are a nightmare

It's all relative; there is no way to guarantee that the program won't
throw up on you the very next time you run it!  If there is no possible
way to verify correctness of the comments, then the code is not understandable,
can not be modified, and must be retired as soon as anything serious 
happens to it.  This is an extreem view, and of course in practice
it's very tedious to verify comments...

>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  
Most comments that I have seen don't document the fact that a program
has a fatal bug.  In fact, usually they state what should be happening,
but the reality is that something happened that the code was not designed
for.  Most times, simply stating what the problem was, and the reasoning
behind the method of the fix is the appropriate action.

>Also, no one wants to take the time to rewrite
>their code into English; 

I agree, this is useless - the code already states what it's doing!
AND I think that this is a perfect example of why comments are not
useful to programmers - as written they don't add any information
to the program.  It's only when you come back the next year that you
have the proper perspective on what comments should have been there!

>it's a boring, tedious job, and when it comes
>down to it only the code really matters to those buying your software.
>It is human nature to take the path of least resistance; comments go
>against this path.  With very few exceptions, for better or for worse,
>this is the way of the world.

...the path of least resistance...   Agreed.  The trick is that the
comments should greatly lower the resistance the next time you look
at the code.  Certaintly, indentation does!

lots of stuff about programmers getting around various requirements deleted.

>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.

Not too much... most maintainers will verify comments if they can.  What's
the alternative?  The alternative is to spend an enormous amount of time
analzying what the code is doing, and knowing that, theorizing about why
it's doing it that way, and what the trade-offs were when the data structures
were designed, whether it was done that way for efficiency, or was it just
the easiest way to do it?  This alternative is what consumes the most time
in software maintenance.  The NECESSITY to do this is virtually what 
DEFINES the nature of the work as maintenance!   If you didn't need to do
this, it is either a very rare program, trivial, or you are still in the 
initial development phase.

Sorry this was so long...


Dave Lewis @ MCC CAD Program [512] 338-3663 | ARPA: lewis@mcc.com
UUCP: {uunet,harvard,gatech,pyramid}!cs.utexas.edu!milano!cadillac!lewis