Level: Introductory Scott W. Ambler (scott_ambler@ca.ibm.com), Practice Leader, Agile Development, Rational Methods Group, IBM
17 Aug 2000 Try these suggestions for what to include when documenting Java member functions.
Every Java member function should include some sort of header, called
member function documentation, at the top of the source code that documents
all of the information that is critical to understanding the function. This information
includes, but is not limited to, the suggestions that follow. What and why the member function does what it does
By documenting what a member function does, you make it easier for
others to determine if they can reuse your code. This documentation makes
it easier for others to put your code into context. You also make it easier
for others to determine whether or not a new change should actually be
made to a piece of their code (perhaps the reason for the new change conflicts
with the reason the code was written as it was in the first place).
Which member functions must be passed as parameters
You also need to indicate how any parameters to a member function will
be used. This information lets other programmers know what to pass to a
member function. The javadoc @param tag is used for this purpose.
What a member function returns
You need to document what, if anything, a member function returns so
that other programmers can use the return value or object appropriately. The
javadoc @return tag is used for this purpose.
Known bugs
Any outstanding problems with a member function should be documented
so that other developers understand the weaknesses and difficulties with
the member function. If a given bug is applicable to more than one member
function within a class, then it should be documented for the class instead of solely for the function.
Any exceptions that a member function brings to your attention
You should document any and all exceptions that a member function throws
at you so that other programmers know what their code will need to catch.
The javadoc @exception or @throws tags are used for
this purpose.
Visibility decisions
If you feel that your choice of visibility
for a member function will be questioned by other developers -- perhaps you’ve
made a member function public before other objects invoke the member function -- you should document your decision. This makes your
thinking clear to other developers so that they won't spend time contemplating
your actions.
How a member function changes the object
If a member function changes an object, then this needs to be indicated.
For example, the withdraw() member function of a bank account modifies
the account balance. This information lets other Java programmers know
exactly how a member function invocation will affect the target object.
Examples of how to invoke the member function when appropriate
One of the easiest ways to determine how a piece of code works is to
look at an example, so including an example or two of how to invoke a member
function is quite helpful.
Applicable preconditions and postconditions
A precondition is a constraint under which a member function will operate
properly, and a postcondition is a property or assertion that will be true
after a member function has finished running (see Object-Oriented Software Construction in Resources). In many ways, preconditions and postconditions describe the
assumptions that you have made when writing a member function (see Building Object Applications that Work in Resources), defining exactly the boundaries of how a member function is
used.
All concurrency issues
Concurrency is a new and complex concept for many developers and, at
best, is an old and complex topic for experienced concurrent programmers.
The end result is that if you use the concurrent programming features of the
Java programming language, then you need to document them thoroughly. Doug Lea (see Concurrent Programming in Java in Resources)
suggests that when a class includes both synchronized and unsynchronized
member functions, you must document the execution context that a member
function relies on, especially when it requires unrestricted access to
allow other developers to use those member functions safely. When a setter
(a member function that updates a field) of a class that implements the
Runnable interface is not synchronized, then you should document
your reasons why. Finally, if you override or overload a member function
and change its synchronization, you should also document why.
An example of documentation
Figure 1 depicts an example of documentation
for a Java member function header. Notice how I have applied standard javadoc
tags, such as @return, as well as non-standard ones, such as @precondition.
To support these new tags, I would need to either develop a doclet
that recognizes them or purchase a Java development tool that can be tailored
to recognize them.
Figure 1. Example member function header documentation
/**
Withdraw the funds from this account.
@param amount The amount of the withdrawal.
@return The amount withdrawn.
@precondition The account must have the funds available for them to be
withdrawn.
@postcondition If the funds are available they will be withdrawn and a record
of the withdrawal will be made.
@throws InsufficientFundsException An indication that the account balance and
overdraft limit were not sufficient to allow the withdrawal to occur.
@modifies Yes Debits the funds and posts a record into the account transaction
history.
@concurrency Changes to an account balance, such as a withdrawal, must occur
as an ACID transaction.
*/
|
The important thing is that you should document something only when
it adds to the clarity of your code. You wouldn’t document all of the
factors described above for each and every member function because not
all factors are applicable to every member function. You would, however,
document several of them for each member function that you write.
Resources
About the author  | | |
Scott W. Ambler is President of Ronin International, a consulting firm specializing in object-oriented software process mentoring, architectural modeling, and Enterprise JavaBeans (EJB) development. He has authored or co-authored several books about object-oriented development, including the recently released The Object Primer 2nd Edition, which covers, in detail, the subjects summarized in this article. He can be reached at scott.ambler@ronin-intl.com and at his Web site at www.ambysoft.com. |
Rate this page
| 
