Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!cornell!rochester!udel!princeton!phoenix!pucc!EGNILGES
From: EGNILGES@pucc.Princeton.EDU (Ed Nilges)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Message-ID: <7211@pucc.Princeton.EDU>
Date: 16 Feb 89 16:04:14 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Reply-To: EGNILGES@pucc.Princeton.EDU
Organization: Princeton University, NJ
Lines: 98
Disclaimer: Author bears full responsibility for contents of this article

In article <9606@ihlpb.ATT.COM>, nevin1@ihlpb.ATT.COM (Liber) writes:

>I'm not.  I do agree with you on the problem (poor documentation), but
>I do not think that more comments is the answer.

     The answer is not "more comments", you're right.  The answer is
     "more programs with better written, more accurate comments; and
     maintenance programmers with more time to update the code as well
     as the comments."

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

     There is also NO WAY of ensuring that the code itself is correct,
     period.  Does this mean we should not write code?  Of course not.
     In my 17-odd years of experience, much of it spent maintaining
     other people's code, I have never been misled by a comment.  I
     have, on the other hand, wasted time where a comment would have
     shown me the way.

     In "no one wants to take the time" you are referring to people
     who like to code before they decide, and WRITE DOWN, what their
     code shall do.  It's my humble opinion that these people shouldn't
     code.  Previous posters to this thread have emphasized that the
     best comments are written prior to code and state the purpose of
     what shall be coded.
>
>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.

     I'd hate to work for someone with such a low opinion of programmers.
>
>
>Suppose you require Joe Programmer to comment every line of his C code.

     Nobody requires programmers to comment C code.  The "every line
     commented" is a standard for assembly language.  C programs require
     instead function purpose statements, placed at the beginning of
     each function.

>
>Here are some real-world examples of what happens when you force a
>programmer to write lots of comments:
>
     These examples describe the behavior of people who should not be
     trusted to program computers.  I do agree that software tools
     can be used to help keep code and documentation up to date; for
     example, I am currently developing a lot of EXECs for VM/CMS,
     and I write the initial "METAEXEC" using Script, both to format
     the descriptive comments and as a macroprocessor for executable
     code.  Since the text formatting commands have access to the
     same SET symbols as does the EXEC code, I can change the value
     of a SET symbol and have the code and comment change at the same
     time:

          .se maxwords = 1500
          .
          .
          .
          /* This software can process at most &maxwords words...
          .
          .
          .
          IF inwords > &maxwords then SAY "Too many words"

     However, it is the maintenance programmer's job to update docu-
     mentation as well as code.
>
>What is needed to improve self-documentation are better programming
>languages.  This is one of the reasons that, for example, C++ is better
>than C; the resulting code is more self-documenting.  The language has
>to make it easier for me to abstract and be more self-documenting than
>not; this is the key to solving the problem.  The ultimate programming
>language(tm :-)) will be one where I will never have to write a single
>comment; it should be clear, concise, and obvious from the code my
>intentions of what I was programming.  We need to improve our
>programming languages, not increase the quantity of our commenting.

     But the best comments are statements of purpose, and the
     Ultimate Programming Language shall not decide for us what
     use shall be made of it!  Also, remember us mortals, who must
     sputter along in FORTRAN and C...

Edward Nilges

"Where is the wisdom we lost in knowledge?  Where is the knowledge we
 lost in information?" - T. S. Eliot