Skip to main content

If you don't have an IBM ID and password, register here.

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. This profile includes the first name, last name, and display name you identified when you registered with developerWorks. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.

All information submitted is secure.

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

Documenting Java member functions

The importance of a header for the code

Scott W. Ambler (scott_ambler@ca.ibm.com), Practice Leader, Agile Development, Rational Methods Group, IBM
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.

Summary:  Try these suggestions for what to include when documenting Java member functions.

Date:  17 Aug 2000
Level:  Introductory

Comments:  

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.

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.


Report abuse help

Report abuse

Report abuse submission failed. Please try again later.


developerWorks: Sign in

If you don't have an IBM ID and password, register here.


Forgot your IBM ID?


Forgot your password?
Change your password


By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. This profile includes the first name, last name, and display name you identified when you registered with developerWorks. Select information in your developerWorks profile is displayed to the public, but you may edit the information at any time. Your first name, last name (unless you choose to hide them), and display name will accompany the content that you post.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

(Must be between 3 – 31 characters.)


By clicking Submit, you agree to the developerWorks terms of use.

 


Rate this article

Comments

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=10465
ArticleTitle=Documenting Java member functions
publish-date=08172000
author1-email=scott_ambler@ca.ibm.com
author1-email-cc=

Tags

Help
Use the search field to find all types of content in My developerWorks with that tag.

Use the slider bar to see more or fewer tags.

For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.

For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.

Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).