Sanesh writes:
> Recently I completed a project that was done using SERVLETS.
>
> I need some help in documenting the application. What is the standard
> way or methods in documenting?
A few months back, a technical writer on another mailing list I'm
on asked a similar question. Keep in mind that the following answer
is an ideal; obviously the closer you get to it, the better, but "no
project is ever released; it escapes."
> 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. 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.
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 handful 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).
To give something of a brief example of the multi-level approach:
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...
Third level description:
.
.
.
etc.
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
[EMAIL PROTECTED]
[EMAIL PROTECTED]
___________________________________________________________________________
To unsubscribe, send email to [EMAIL PROTECTED] and include in the body
of the message "signoff SERVLET-INTEREST".
Archives: http://archives.java.sun.com/archives/servlet-interest.html
Resources: http://java.sun.com/products/servlet/external-resources.html
LISTSERV Help: http://www.lsoft.com/manuals/user/user.html
