Software maintenance is a significant part of the effort and cost put into an application over its lifetime, so writing code documentation for an application is essential. Unfortunately, code documentation often ends up on the "do later" list, and your amazing code later becomes a problem child to maintain. Luckily, Java programmers have at their disposal a tool to make documenting code easier.
With a few simple guidelines, you can create killer code documentation using Javadoc, a tool that ships with Sun’s JDK toolkit. You can then ensure that you leave smiles on the mugs of the programmers left to follow your code after you move on to a bigger and better project or company.
The Javadoc utility works by creating a set of HTML files out of the Java source files that end in a .java extension. Within your comments, you can add HTML tags to control the format. Comments included in the HTML files include those that start with a double asterisk.
With a bit of planning, you can become the programming guru who is also known for amazing documentation skills, because Javadoc renders specially marked comments into lovely HTML code. In fact, even if you never enter a single code comment, Javadoc produces a fine set of HTML pages that make the code easier to decipher.
You already build strong comments as part of your routine? Then you know that consistency and simplicity are critical in any good standard. For Sun’s recommendations on developing and documenting your source code, see "How to Write Doc Comments for the Javadoc Tool.”
Make your docs even better with these tips
Even though Javadoc does a lot of the work, you can greatly improve the quality of your documentation by applying some standards and consistency to your comments. Here are 10 tips to get you started:
- Save time. For package documentation, start with the template and comment as you go.
- Work with your writing staff to adopt an official set of standards for your code documentation. You may want to adopt an already published style guide and make minor customizations. (Why not take advantage of the knowledge someone else paid to obtain?) Distribute the guide among the project team members and check periodically for compliance.
The Elements of Java Style, also known as the RogueWave Java Style Guide, provides a straightforward presentation of techniques for producing good documents and makes recommendations for building good code, too. This set of standards was created by a development shop specializing in Java and C++ development for “programmers who are writing Java as part of a team.”
- Create a comment for each protected or public member variable, method, and class. It’s important to note that creating names for variables, methods, and classes is the first opportunity to convey how the code works. If you create meaningful names in the first place, you eliminate the need for lengthy comment. A good question to ask is, “Can the next programmer who looks at this code understand how it works by reading the name?” When the name doesn’t fully convey how the code works, use comments to explain their purpose, any variables, etc.
- Because member variables, methods, and classes usually describe things rather than actions, you can write a succinct phrase such as
"This field is a text box."
- Follow Sun’s guidelines for using and ordering tags. For ordering multiple tags, list them in the following order:
@author: List chronologically
@param: List in argument-declaration order
@exception: List alphabetically
@see: List from “nearest to farthest access, from least-qualified to fully qualified”
- For the tag @param, indicate whether a parameter can be null or is required.
- Keep the writing style active and simple. Sun recommends that the first sentence of each doc comment should summarize the member, class, interface, or package and that you use phrases rather than complete sentences. (Note that if you use any abbreviation ending with a period, then a blank, tab, or line terminator, you should type an HTML metacharacter such as   immediately after the period if you want your full sentence included in the summary created by Javadoc.)
- Code comments should be used to help programmers understand what code does. Use comments to explain code and use a source code control tool to audit code changes and track defects. If you choose to document bugs in the comments anyway, provide a consistent, easily recognizable format to minimize clutter.
- Create a procedure in the top of class documentation if a class will be reused (extended) into many subclasses and there is specific set of steps to implement them. List each step in the process and use HTML list tags (<ol> or <ul> and <li>) to format the comments.
- Generate a new set of HTML files at regular intervals, such as once a week, to make sure necessary information has been captured and to edit information while it's still fresh in your mind or the minds of team members.
Writing program documentation may never be fun, but it is necessary. With Javadoc, the task of documenting your Java programs has just gotten easier. And if you follow some simple standards as you write your programs, there is no reason you can’t be known for world-class documentation as well as world-class code.