Re: The Last Word on Comments (was Re: Hungarian notation)

[Richard Riehle <rriehle@nunic.nu.edu>]

On Thu, 13 Jun 1996, Kevin D. Quitt wrote:

> On Mon, 3 Jun 1996 16:24:18 GMT, bobduff@world.std.com (Robert A Duff) wrote:
> >Clearly, an Ada program needs fewer comments than an
> >assembly language program, and that's a benefit.
>
> If you have this attitude, you'll never work for me.  Comments tell me what
> the program is doing and why; the comments are high-level.  The code shows
> how, with comments to explain unusual techniques.

  Your assessment of Dr. Duff's value to a project may be a little
  hasty.  Though he is quite capable of defending himself, my guess
  is that he did not mean to imply that comments were always
  superfluous, rather that one needs few comments in a high-level
  language than in a low-level language such as C or Assembler.

  I recall, from my Assembler days, that nearly every line needed
  some comment if we intended it to be maintainable.

  OTOH, on an Ada project, the convention was to comment every
  exported service in a package specification with a direct or
  indirect reference to the corresponding paragraph in the original
  requirements specification document.

  Comments, in Software Engineering, are as important for traceability
  as for "what is really going on here?"

  For projects where the deployed software will involve a human user,
  we sopmetimes recommend to our clients that they first write the user
  manual. Then build the software with comments traceable back to
  chapter and verse of that manual.

> When I've led teams with junior people, I've told them that their comments are
> much more valuable than their code.  If their comments are legit, I can
> immediately tell if there's a design problem.  And if there isn't a design
> problem, I can code from their comments and make it work a whole lot faster
> than they can debug.

  This is undoubtedly true for languages which discourage the programmer
  form writing code with meaningful data names.  In fact, this is
  precisely the problem with "write only" languages such as C or APL. It
  is unfortunate that this carries over to much of the C++ code I
  encounter. C++ does have the potential for supporting self-documenting
  code even though that potential is seldom realized in practice.
  In such situations, one is truly dependent on the quality of the
  line-by-line comments.

  In languages that stress readability of the final code such as Ada
  Eiffel, or Modula-x, embedded comments are somewhat less critical. For
  these kinds of languages, the programmer finds the code itself to be
  a bit more friendly.  In such situations, comments may be helpful. Other
  times,  when the comments are overly verbose or extraneous, their very
  extraneousness can actually hamper rather than enhance understanding.

  Richard Riehle