Andrew Binstock's recent review of the book Clean Code: A Handbook of Agile Software Craftsmanship got me thinking about what I like and dislike about working with Javadoc. The specific comment that started me thinking about this was the observation that the both authors (primary author of the book and author of the blog review) feel that "Javadoc should not contain HTML." I am somewhat torn on this and often compromise with minimalistic HTML (such as <p> tags to separate paragraphs in package and class descriptions rather than allowing the text to be all munged together in HTML).
There is really a bigger issue at the heart of this: who is your Javadoc intended for? In this blog entry, I intend to discuss some of the things I have found that have made the Javadoc I generate or consume (others' documentation) to be more effective. The audience for the Javadoc is often the most significant consideration when considering what should go in the Javadoc comments.
The Case for Javadoc
I'll start by saying that I do think there are times when Javadoc is essential, times when it is helpful, and times when it is just about useless. Even worse, it can be harmful if allowed to become stale and overcome by events as the code changes. Useless Javadoc is often written as a result of mandated conventions or processes, but the other extreme is writing no Javadoc at all. I find myself writing very simplistic Javadoc comments for routine things such as get/set methods and no-argument constructors, but I do tend to write some Javadoc for all public methods and other publicly available Java constructs.
Documenting all publicly exposed APIs of a class is one of the items that Joshua Bloch calls out in Effective Java (Item 44 in the Second Edition and Item 28 in the First Edition). In addition, he points out the usefulness of documenting exceptions (Item 62 in Second Edition/Item 44 in the First Edition) and documenting thread safety (Item 70 in Second Edition/Item 52 in First Edition).
The most common argument against writing Javadoc is that clean code should speak for itself and that comments are only needed to act like deodrant when the code is smelly. There is certainly truth to this for comments in general, but I think some comments are appropriate some of the time and I have found Javadoc comments to be very helpful in my work.
The value of Javadoc comments certainly depends on the use of the code being documented and its audience. I rarely look at the source code of the JDK. Instead, I use its Javadoc-generated API documentation. Why do I use the Javadoc instead of looking directly at the source code? There are numerous reasons. I have it bookmarked in my favorite browser, so it is easy to access. My favorite IDE references Javadoc for me automatically as I use the IDE's code completion and other functions. Finally, I rarely need more detail than what is provided in the Javadoc for the standard Java libraries. Similarly, I find myself using the Javadoc for other open source products (Spring Framework, JFreeChart, etc.) far more than I actually look into their code. I usually only look at the code of these products if I need to explain an unexpected behavior, need to know exactly how something is being done rather than what is being done, or am curious about the implementation. This is even true of the non-Java frameworks I use. For instance, I heavily use the Javadoc-like Flex 3 Language Reference.
Other perspectives on the value of Javadoc are available in The Importance of Humble Javadoc, To Javadoc or Not Javadoc That is the Question..., and The Value of Javadoc.
Tips for More Effective Javadoc
With the case for useful Javadoc comments made above, it is time to look at a few detailed tips that I have found useful in writing effective Javadoc documentation. I realize that there are many more tips and useful practices related to Javadoc that I am not covering here. Feel free to add any you have found useful to the comments section.
You Don't Necessarily Need to Javadoc Everything!
There are situations where the boss, the client, the process, the code convention, or someone or something else requires you to write Javadoc comments for every thing in your code. These types of edicts are often what turn developers away from writing truly useful Javadoc. Often, the baby (good and useful Javadoc) is thrown out with the bath water (time-consuming and largely useless Javadoc).
I'm a strong believer that efficient Javadoc is often effective Javadoc. If one has documented data members and chosen to employ the -private option when generating Javadoc, then get/set methods for that particular data member likely do not need to be documented. For external purposes, Java developers may not want to expose the intentionally private, protected, or package level data members in the public API documentation. In this case, documenting the get/set methods can add value because this can be one of the easiest places to advertise to client code the valid values (range), units, and whether null is allowed or possible for that data member.
If I'm developing code for internal use only by other developers within the organization, I might favor documenting the data members and turning on private documentation generation. However, if my audience is an external one, it might be preferable to document the accessors and mutators. Adding Javadoc commenting to a no-arguments constructor may be superfluous at times, but it can also be useful when explaining why that constructor is not public and what constructor or builder should be used instead.
Some situations I find myself writing very little Javadoc for include JUnit tests and for the data members of nested builder classes as outlined in Item #2 of the Second Edition of Effective Java. In the latter case, the data members of the nested class essentially mimic the data members of the enclosing class, so rather than document those data members in both places, I prefer to reference the comments of the enclosing class's data members.
Sometimes, the code can speak for itself. Other times, there is no good way to communicate the intricacies or decisions made that led to something in the code without comments (especially Javadoc). Finally, it is worth noting that Javadoc becomes more important in situations where non-developers (test personnel, for example) might be using your Javadoc to better understand the application. I try to think about who will be using my Javadoc rather than just my own perspective when deciding if Javadoc for a particular element is useful or not.
The First Sentence Matters
Not all text within a particular Javadoc is created equal. The first sentence of the Javadoc for packages, classes, and methods is especially vital because that is what appears in summary information about those respective Java elements. Therefore, it makes sense the effort should be placed in making that first sentence as concise and useful as possible. Often for simpler cases, the most efficient Javadoc can be written with just a single sentence, satisfying both the previous recommendation regarding minimalistic Javadoc and satisfying this recommendation to make the first sentence matter.
Use -linksource for Source Code Accessibility
This is another tip that depends on the audience. Because the debate on whether to use Javadoc or code that speaks for itself (I try to do both as much as possible with emphasis on minimalistic but useful Javadoc), using the -linksource option can increase the value of the Javadoc-generated documentation for both sides of the debate.
The -linksource Javadoc option allows the class names in the Javadoc-generated documentation to link to a copy of the source code itself. By clicking on the class's name, the viewer is taken to that class's source code with line numbers. A good example of this is the JFreeChart API documentation. One can select any of the classes in that library (such as the highly significant JFreeChart class) and then click on the class name after "public class" to see the source code.
An important caveat here is that all source code is made available via the -linksource option regardless of whether -private is used or not. This caveat is a reminder about the importance of considering the audience of your Javadoc comments.
Document All Thrown Exceptions
It is useful to advertise to a method's potential clients what exceptions the method might knowingly throw. This is more obvious for checked exceptions due to the throws clause on the method definition, but that clause only indicates what type of checked exception will be thrown. The @throws Javadoc tag can be used to explicitly specify the checked exceptions that might be thrown and why they might be thrown. The @throws tag can also be used to document unchecked (or runtime) exceptions in the same way even those these are not documented in the method definition.
Document Parameter Details
The @param Javadoc tag allows one to specify what each parameter to a method represents. This is where significant information about the parameter can be specified such as allowed range, whether null is allowed or not, and any relevant units for that parameter (such as if the expected unit is seconds or minutes). Some of this can be specified by parameter name (such as secondsUntilOperationIsFinished), but it actually becomes less readable to include every detail about the parameter in the name (secondsUntilOperationIsFinishedCannotBeNullMustBeBetweenZeroAndSixtySeconds).
Much of this discussion also applies to the @return tag, where range, null or not null, and units considerations are often important.
Document Package and Class Usage
More recent Java packages and classes in the JDK seem to have better descriptions of how to apply those packages and classes. A good example of this at the class/interface level is the highly informative Javadoc documentation for the JAXB Marshaller and Unmarshaller interfaces. Each of these interfaces demonstrates how the respective interface can be used respectively to write out XML from bound Java objects and read XML into bound Java objects. The javax.management package description similarly provides an example of a highly informative description of how a package and its significant classes are used.
Many of the SDK descriptions provide links to non-Javadoc references on the subject and the Spring Framework does the same thing with links to its reference documentation from its API documentation. This is often accomplished with {@link}, available since JDK 1.2 with closely related {@linkplain} available since JDK 1.4. Overview and package-level documentation can provide a valuable pointer to where to start with the library or framework being documented.
It is not surprising that the JAXB interfaces and JMX package referenced above have such highly information Description sections because these are likely to be used by Java developers of many different skill levels. The audience here is Java developers of a wide variety of skill levels in terms of both breadth and depth and so it is helpful to provide relatively introductory information into how to use these interfaces, packages, and APIs. Such descriptive details may not be as important for a small team consuming their own code and its Javadoc documentation.
Use HTML Carefully in Javadoc
Javadoc allows HTML tags to be embedded in the Javadoc comments. While this is handy for nicely formatted and styled HTML presentation of the comments, it can be distracting for the person trying to read the comments directly in the code. Many of the IDEs mitigate this problem to a certain degree by doing their own representation of the tags rather than listing the tags directly. However, too many HTML tags can still be a burden for the reader and maintainer of those comments, especially when they are using a text editor or IDE that doesn't process the Javadoc tags in any special way. On the other hand, the nature of HTML is such that even basic things like white space beyond a single space noting be respected in the output can lead to ugly and hard-to-read HTML if no tags are used.
It definitely seems more like art than science to find the happy medium between too little HTML and too much HTML in Javadoc comments. If you know your audience is primarily developers reading the code directly, you might be best suited to writing little or no HTML in your Javadoc. If, however, you are delivering a framework or library or are in some other context where people without access to the source code or without a desire to read source code will be significant users of the HTML version of your Javadoc, the HTML tags might be more important. This is especially true if the goal is to reduce documentation to the code itself with little or no external design or implementation documentation. In that case, you almost certainly will have clients, managers, testers, or other stakeholders who prefer the HTML documentation over readable in-code Javadoc.