Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!cornell!uw-beaver!apollo!perry
From: perry@apollo.COM (Jim Perry)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <419ca3bc.183dc@apollo.COM>
Date: 21 Feb 89 20:42:00 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Reply-To: perry@capsicum.UUCP (Jim Perry)
Organization: Apollo Computer, Chelmsford, MA
Lines: 70

In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:
>In article <4173bd76.183dc@apollo.COM> perry@capsicum.UUCP (Jim Perry) writes:
>
>>Let me begin by saying that I'm in the camp calling for more comments.
>
>I'm not.  I do agree with you on the problem (poor documentation), but
>I do not think that more comments is the answer.
>
>>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.
>
>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
>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  Also, no one wants to take the time to rewrite
>their code into English; 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.
>
>Will requiring Joe Programmer to write more comments fix the situation?
>No.  

(examples of how Joe Programmer sleazes his way out of writing comments).

This attitude is one of the best arguments I've seen for distinguishing
Software Engineering from Programming.  Jane Engineer writes comments not
because someone is requiring her to, but because she knows that this
code is going to be around for a long time, and that the initial writing
is a tiny fraction of its lifetime.  Jane Engineer's had the pleasure of 
trying to modify a piece of Joe Programmer's undocumented code, and doesn't 
want the next person to work on her code use words like that about *her*.
For that matter, there's every chance that next person will be Jane herself
two years from now.  Joe's now selling shoes in Peoria, by the way.

"Rewrite their code into English" shows a basic misunderstanding.  Code
expresses some underlying algorithm which you should have thoroughly 
thought through before rendering it in C.  Your comments should be a
parallel rendering into English.  If anything, you should write
comments *first*.  Proper documentation naturally complements the code.

While it's true that there's no way of guaranteeing that comments agree 
with the code, the reverse is equally true.  If the comments are a good
English synopsis of the desired intent of the function, and the code
doesn't agree, there's every chance that the code is wrong.  If Joe
Programmer hacks up Jane Engineer's code without updating the comments, 
confusion can arise, but that's a worst-case scenario that's never bitten
me badly.

>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.
>
>What is needed to improve self-documentation are better programming
>languages.

As you point out earlier, this is the Real World.  Some bright sunny day
we might have such languages, but the fact is we're stuck with C for quite
some time now, and C is more self-obfuscating that self-documenting; the
comments are all you've got.  
-- 
Jim Perry   perry@apollo.com    Apollo Computer, Chelmsford MA
This particularly rapid unintelligible patter isn't generally heard
and if it is it doesn't matter.