Re: Code Documentation

["Steven J. Owens" <puff -at- NETCOM -dot- COM>]

Tracey Moore writes:

> My company has recently completed a visual basic/java application
> and we now need to document the code. (All we've done so far is print
> out the code itself.) Does anyone out there have experience with this?

     Depends, of course, on what "document the code" means.  Peter, Jim
and Bruce gave excellent advice.  Here's a bit more perspective, assuming
you're talking about documenting the source to help a programmer later
modify, maintain, or analyze the code.

     The program consists of one or more object classes, each of which
has one or more methods that interact with each other and other
objects.  You should document at four levels:

     The first level, the overview, should describe each object, what
it does, and which of the other objects it interacts with, and how.

     The second level should describe each object in terms of the
methods and the object variables, and what purposes they serve, and
which methods call other methods.

     The third level should describe each method in general terms, the
general structure of the method, which other methods and variables it
calls, and even which methods it expects to be called from (this last
is most likely to get changed over time, but at least it will give the
reader an idea of what the method was designed for).  The arguments to
the method should be described, specifically what they *mean*, where
they're probably set elsewhere in the program, and what the method
will do to them or use them for.

     The fourth level is comments in the source code of the objects
and methods themselves.  Focus on why something is being done, and not
just what is being done.  "Decrement the counter" as a comment isn't
terribly useful.  Knowing where the counter is from, where it was set,
what it's counting, and why it needs to be decremented would be
better.

     Part of the "documentation" at the fourth level is simply code
style for legibility & comprehensibility.  A good indentation style,
grouping things so they can be easily understood.  Put the accessor
methods at the beginning of the object.  Put the mutator methods next.
Then probably the handful of methods that do most of the work, and are
called by the accessors and mutators.  Then specialized methods
(usually rather short and singular of purpose, and only called from
the handul of methods that do most of the work).

     Name methods and variables appropriately so it's easy, having
read the read of the code, to guess what a method is doing.  Also
name them so they make it explicit what they are.  For example, if
a variable is a static configuration variable then name it so it
reflects that, and unless they're commonly used throughout the
program, include a comment when you use it, so the reader can understand
what method initializes the variable, and also note where that method
was invoked from.

     The documentation should be incorporated into the source code, so
it will always be where the code is.  The compiler will remove it when
it's compiled.  The third level stuff should be at the beginning of
each method.  The second level stuff should be at the beginning of
each object.  The first level stuff should probably be at the
beginning of the main object.  All of the levels will overlap to a
degree.

     Changes should be noted in comments at the point the code is
changed, including a date/time stamp, and in a master list of changes
at the beginning of the main object (with pointers to the location
in the code where the change was made).

Steven J. Owens
puff -at- netcom -dot- com


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=