Re: Easily-Read C++?

[ncohen@watson.ibm.com (Norman H. Cohen)]

In article <37emcj$sk5@gnat.cs.nyu.edu>, dewar@cs.nyu.edu (Robert Dewar)
writes: 

|> There are to my mind three justifications for comments: 
|>
|> Saying WHY you are doing something, and WHY you did it that way
|>
|> Saying WHY you did NOT do something, and WHY you did NOT
|>
|> Describing WHAT the code does, but at a higher level of abstraction
|> than the code itself.

Another purpose is to leave advice to future maintainers about how to
add enhancements that you have anticipated: 

   -- Additional devices can be accommodated by deriving new
   --   types from Driver_Type.

   -- To add a reserved word, simply add it to the aggregate used to
   --    initialize Vocabulary.  Add the new word in alphabetical
   --    order so that the binary search in Lookup will continue to work.

In modifying other peoples' code, I've sometimes found comments
performing another useful function as well:  Utterly incoherent comments
warn the reader that the original programmer had no idea what the
*(^%(*$)%!! he was doing, so that the reader knows to regard the code
with suspicion.

My favorite comment (for honesty, if nothing else) comes from a ksh
profile: 

   #the next two lines are copied from the korn shell paper
   #i don't know why it works, but it seems to

The runner up comes from an assembly-language program: 

   xor R3,R4,R3    THIS IS TRICKY.

--
Norman H. Cohen    ncohen@watson.ibm.com