Re: comments on comments

[rjh@cs.purdue.EDU (Bob Hathaway)]

Dave Jones [djones@megatest.UUCP] Writes:
>Here are some remarks that I wrote up for one of the
>members of my programming team.  I hope they will be
>helpful.

Thanks, I agree good documentation is invaluable.

>
>In my opinion, the most important parts of a program to document
>are the structure-declarations and the variable-declarations.
>

This is true, but alternate design strategies can call for an
extended perspective on documentation.  When using an object
oriented design strategy, I'll first write a design document
describing the primary objects in the system and their operations.
Also in the document will be a high-level description of the
important procedures written in an informal PDL, such as a pseudo
Ada code.  For objects (Adts), first is a description of the object and
its rational and system context.  For instance, what the object is
intended for, why I chose an abstract data object or an abstract data
type, and possibly how it will interact in the system, but
the last part could go in a separate document as pointed out
by Dave Jones.  Second is a numbered list of operations and their 
descriptions.   When the entire system is complete, the declarations
can be coded in a higher-order language.  In Ada, the design is directly
implementable as compilable specifications.  In Modula or some other
language in which the specifications aren't compilable the procedures
can be filled in with stubs or empty declarations.  The design document
can be included as comments and updates to the document and code should
be done concurrently.  The object descriptions are included in the
specifications and optionally in the package or module body, and the
(numbered) operation descriptions included for each procedure or method.

>Here's a good way to go about it:
>
>/*******************************
> * This is one block comment,
> * and it is easy to modify.
> ******************************/
>

Here's another way:

/*
 * my_procedure
 *
 *    <ADT design document index>
 *    This is a description of...
 *    ...
 */

             Bob Hathaway
             rjh@purdue.edu