Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!ucbvax!hplabs!hpda!hpcuhb!hpsmtc1!ham
From: ham@hpsmtc1.HP.COM (Bob Hamilton)
Newsgroups: comp.software-eng
Subject: Re: comments and correctness proofs ( Re: comments on comments )
Message-ID: <16090009@hpsmtc1.HP.COM>
Date: 22 Feb 89 21:10:22 GMT
References: <1859@goofy.megatest.UUCP>
Organization: Hewlett Packard, Cupertino
Lines: 42

> Your comments should be a parallel rendering into English.  If
> anything, you should write comments *first*.  Proper documentation
> naturally complements the code.

BRAVO.  Yes.  Precisely.

My brother once told me "When I'm given an assignment, I first write the
user documentation.  Then I show it to the person in the next cubicle.
When we both agree, I show it to other people on the corridor.  When we all
agree that the user documentation is complete and correct, writing the code
to implement it is trivial."  

This may be an over-simplification, and please don't flame my brother, but
it does illustrate the point I'm trying to make.

When I reached the point where I was writing new applications, I had been
maintaining old ones for some years.  I had been called in the middle of
the night to come in and fix other people's stuff more times than I can
count (I was in MIS operations support).  By the time I began writing
serious amounts of code, I had formed some conclusions about comments:

  1.  Know your audience:

      A.  Does this person know {more, same, less} about the language than
	  you do?  Comment accordingly.

      B.  Does this person know {more, same, less} about the application
	  and its environment?  In my case, probably less, comment accordingly.

  2.  Comment on the assumption that the reader has just been called in at
      2:00 AM, doesn't know the language very well (or s/he wouldn't be
      junior enough to be dragged out of bed), and is seeing this whole 
      mess for the first time.  Try to give enough information that a
      reasonably intelligent person can figure out what's going on well
      enough to solve any immediate problem, and come in tomorrow and
      make the fix pretty.
      
--Bob Hamilton
  Software Methods Lab
  Hewlett Packard Company
  Cupertino, California
  (408) 447-5113  ham@hpda