Skip to main content

skip to main content

developerWorks  >  SOA and Web services  >

Documenting Java member functions

The importance of a header for the code

developerWorks
Document options

Document options requiring JavaScript are not displayed


Rate this page

Help us improve this content


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).



Back to top


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.



Back to top


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.



Back to top


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.



Back to top


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.



Back to top


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.



Back to top


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.



Back to top


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.



Back to top


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.



Back to top


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.



Back to top


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


Please take a moment to complete this form to help us better serve you.



 


 


Not
useful
Extremely
useful
 


Share this....

digg Digg this story del.icio.us del.icio.us Slashdot Slashdot it!



Back to top