Simplify Your Java Documentation Strategy

Documentation is an afterthought for many development teams. But if it’s properly managed, spending a few minutes now on documentation can save a lot of future work. At its heart, Sonar is about technical debt – the things that were done poorly or left undone – things that will stand in the way of future productivity. Get some ideas for making your Java documentation process a smooth activity.

This article is based on Sonar in Action, to be published in Summer 2013. This eBook is available through the Manning Early Access Program (MEAP). Download the eBook instantly from manning.com. All print book purchases include free digital formats (PDF, ePub and Kindle). Visit the book’s page for more information based on Sonar in Action. This content is being reproduced here by permission from Manning Publications.

Authors: Patroklos P. Papapetrou and G. Ann Campbell

 We’re all eager to finish the real code (don’t forget the unit tests) and see our systems running. And any activity that doesn’t advance this goal is (seen as) unnecessary. But the truth is that, unless you’re on a one-man project like Lucky Luke and plan to remain a one-man shop, maintaining the same old code over and over for the rest of your career, you have some obligations to your fellow coders. The code you write does not belong to you and it’s certain that, during a project’s life-cycle, other developers will need to modify it or use it. Don’t fall prey to the stereotypical developer egotism: “My code is straightforward. It’s not my fault if you don’t understand it; try harder.” Or, stated more cynically: “The code is the documentation.” Instead, remember that at some point you’ll be the new guy on a team again. Write the documentation that you’d like to read in that situation and always remember that you’re part of a team.

 

Figure 1 Documentation is a mutual activity. You take advantage of other people’s comments as they do of yours

Picking a documentation tool

Let’s stop pointing fingers and look at how to improve your documentation process. First, every member of the team must commit to following the process. Anyone who’s not on board should get off the bus at the next stop and hope another one comes along.

Once you have agreement among the team members, you need to pick the tool and the format you’ll use for your comments. The standard in Java is Javadocs. If you’re among those who think default Javadocs looks ugly (indeed they do), keep in mind that you can create a custom XHTML doclet to provide good-looking and professional documentation. For other languages, there are similar tools, like NDoc for C# and Doc++ for C and C++. There’s also Doxygen, which has nice Sonar integration and can be used for several languages, including Java, C, C++, Python and PHP. You could even use a combination of tools for best results and customize them to fit your needs. In general, they’ll all give you smart and effective ways to apply comments in your source code.

Defining a straightforward process

Now that you picked a documentation tool, it’s time to define an easy-to-follow process. To do that you’ll need to answer some simple questions:
* When we should write documentation?
* What parts of our source should we document?
* What information should the documentation include
* Should we automate documentation generation or not?

Your answers will guide you in creating the process that best fits your team’s needs. Here are our suggestions to keep it simple and elegant:

When to document

First, document as you code. Before you start a new class, jot a few comments explaining its purpose. The same applies to methods/functions. Briefly describe what they are expected to do.

After finishing the code, review the documentation and update it to reflect any changes you might have made (see figure 2). Whenever you need to modify a piece of code, follow the same steps. By applying this short process as part of your development methodology, you can be sure that every new or modified method is correctly documented.

Figure 2 – Simple documentation process

Which parts of the source to document?

Every public class and each of its public methods and properties is a candidate for documentation. But there is no need to document setters and getters or other methods that are so simple that the signature itself is the explanation. The snippet below shows one of our favorite over-documentation anti-patterns:

private String name;
/**
* Returns the the name
* @return name
**/
Public String getName()

In this case, the Javadoc doesn’t provide anything that the reader couldn’t have gotten from the method signature itself. Which means it’s entirely redundant. And, like other duplications, it should be avoided because redundant documentation, like redundant code, needs to be maintained but doesn’t usually get that attention. Instead, it only adds noise to your source code, or worse – it stops reflecting the actual purpose of the code because it’s not kept up to date and adds confusion instead of clarity.

But you do need to document private methods even though they won’t change the numbers you see in Sonar. Why bother? So that future developers maintaining the code (including you, six months from now) can quickly understand the purpose of each method by reading the clear and insightful summaries you’ll write instead of having to slog back through the logic to figure it out the hard way. This will increase productivity and make your code more maintainable (not to mention making the future you a little justifiably smug about what great documentation you write).

Documenting public methods is useful for both maintainers and people who use your package.
Documenting private methods is useful for maintainers of your package (including you).

Anonymous

What information to include

Apart from describing the purpose of each class or method, it’s a good idea to include descriptions of input and output parameters as well as any exceptions that might be thrown. When appropriate, you may also want include things like the version of the API that introduced a particular feature. Include everything you think is important and keep in mind that documentation should be complete enough that the reader won’t need to ask for clarification. Popular IDEs like Eclipse and NetBeans offer many ways to facilitate this process, including documentation templates that fill in basic information for you and let you focus on the real work.

What you should avoid is also as critical as what you document. Try not to comment-out lines of real code. Delete them instead. If you need them back, you can always revert to a previous version of the file from your source control system. Why add “noise” to your code?

Another thing to avoid is comments within the body of a method or function. It has become a generally accepted principle that, if your code needs comments to be understandable, what it actually needs is refactoring. Either better describe the method in you API comments, or clean up your code. Refactoring or using better names for variables, methods, and classes are two techniques that make your code self-documenting and remove the need for extra comments.

How to generate

There is one last thing. When you start writing documentation comments, you need to decide how you should generate and publish the docs. Manually or automatically? Continuous Integration (CI) can make the development process go a lot more smoothly by offloading the tedious, repetitive tasks to computers (where they belong) and leaving you and your teammates free to tackle the interesting stuff. There are manual ways to generate your code docs but ideally you’ll set it up as part of your CI process so that no one has to remember to do it and it’s always up to date.

Summary

All code should be documented, even when its use it limited to a single team. But documentation becomes critical when you’re writing libraries for use by other teams or companies. You now know how to approach setting up an easy-to-use process to improve the documentation in your projects and which bad practices you should avoid.