TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Code Documentation From:"Steven J. Owens" <puff -at- NETCOM -dot- COM> Date:Wed, 4 Nov 1998 15:02:29 -0800
> 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
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
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() 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
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.