Re: Code Documentation

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

I wrote:
>      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.

     I left something out here - or more to the point, I was too
vague.  This section should look at the code more as a whole, not in
the components.  It should document the flow of execution and the
relationships (method calls) among the objects, not simply list each
object and the methods and variables associated with it.  For example:

     First level description of the XYZZY thesaurus server:

     xyzzy - the main object, starts the program, instantiates
          configuration (which instantiates thesaurus), instantiates
          a pool of portlisteners, which listen at the configured port
          for a request and then look up synonyms in the thesaurus object.

     configuration - loads the configuration file, parses it, sets all of
          the configuration variables, and instantiates the thesaurus.
     thesaurus - the thesaurus data, a static object globally available
          to the rest of the program, instantiated by the configuration
          object.

     portlistener - instantiated in a pool by xyzzy, takes turns
          listening at the port to serve the next request.

     Second level description:

              xyzzy.java is the main object; execution starts when you
         load the class and the main() method is invoked.

              xyzzy.main() method calls the xyzzy.load_config()
         method, which instantiates configuration.java (invoking
         configuration.init()), and saves the returned values as
         object variables.

              configuration.init() loads in the config file, sets all
         of the configuration options, including file locations, how
         many port listener objects to maintain in the pool, port to
         listen on, permissions, etc, see configuration file or
         configuration.java source for details on which options are
         configurable.  Then init() invokes
         configuration.load_thesaurus().

              configuration.load_thesaurus() instantiates the
         thesaurus object as a static class variable, passing the
         thesaurus data file in from the configuration file.

              configuration.init() returns references to the the
         configuration options and the thesaurus object to
         xyzzy.main().

              xyxxy.main() instantiates a pool of portlistener objects
         and invokes portlistener.listen() with the port number as an
         argument on the first portlistener.

              portlistener.listen() listens on a port until it gets a
         request, whereupon it relinquishes the port back to
         xyzzy.main() to assign a new portlistener, and invokes
         portlistener.do_request() to asnwer the request.

              portlistener.dorequest() invokes thesaurus.lookup(),
         passing the arguments of the request...


     If you produce a printed form of this, it helps to use some sort
of visual cue (indentation, boxes, colors, whatever) to delineate the
methods that are internal to an object.  In code source, indentation
usually piles up too quickly and you end up indenting 40 spaces, which
just gets too unwieldly.

     Note: The configuration file mentioned above should include
copious comments before each configuration option, explaining what it
means, what the various options are, and recommending a course of
action for the user.  The "default" configuration should work, if
there are things that can't be left to the default, the installation
program should figure them out or explain the question to the user and
get the data and set the configuration.

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

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