Java Documentation Tips and Tricks

Java documentation is important to do, but hard to love. Those little @link and @author tags are time-consuming to write but vital to improving the readability of the program.  

Fortunately, there are even extensions that can generate JavaDocs for you using AI. Read on to learn more about Javadocs best practices, JavaDocs utility options, using AI extensions to write Javadocs, and more. Read on to learn: 

What Are Javadocs?

JavaDocs are a streamlined and structured way to document classes, interfaces, methods, and variables. It is not recommended to define multiple variables in a single comment. 

By creating clear, concise, and informative documentation in their Java code, Java developers create code that’s easier to understand.  

Are Javadocs Still Used?

Javadocs were introduced in the first JDK release and have been updated in every JDK release since. Today, many IDEs allow you to use an AI assistant to generate relevant Javadocs.  

Example of Java Documentation 

You might not forget the importance of a piece of code you write, but that doesn’t mean that someone else picking up where you left off will instantly understand it.  

Let’s take the following example: 

1. Write the following class body public class BurgersManager { }
2. Think: “Well I should have some CRUD ops in that manager”
3. Write some: public...
4. Think “What should I return? Well void will be good for now”
5. public void addBurger(Burger burger) { // TODO implement that later } public …
6. Think: “Should I return the instance of the eaten burger or void will fit? Well, like #4 rules …”
7. public void eat(Burger burger, boolean fast) { // TODO …
8. Tell to myself: “Oh dang, coffee time. Where is my coffee …”
9. Searching, drinking, talking to colleagues
10. Then telling to myself: “Let’s get back to work. What was I doing?”

Thinking documentation before code will help you clarify your mind and lay out clearly what you need to achieve with the code. The first step could be writing the following code: 

/**
 * This class allows to manage burgers by providing CRUD operations using burgers and 
 * acts as a singleton. In order to get the instance of this manager, the method 
 * {@link #getInstance()} can be used. Then CRUD operations can be called like the following:
 * 

{@link #addBurger(Burger)} in order to add a burger that will be managed by the * singleton instance ;

* @author Thierry Wasylczenko * @version 0.1 * @since BurgerQueen 1.0 */ public class BurgersManager { }

 

This is a short example that:

• Forces you to think what is the purpose of the class you are creating
• Helps you identify your needs
• Reminds you what you are doing, even after taking your break
• Helps you estimate what still needs to be done

Why Javadocs Help Teams Collaborate

You are probably not working alone, and you may have colleagues you respect and with whom you love drinking coffee and talking about things, including your exciting BurgerQueen implementation. With proper Javadocs usage, you can answer questions about the thought processes behind your code even weeks after the fact.  

Quality Java documentation helps teams avoid: 

• People being interrupted in they work and then having difficulties to recover from the interruption
• People looking for the right person who could answer a question and disturbing other teammates to know if they know who could answer
• People waiting for teammates to be available to answer their questions 

Best Practices for Using Javadocs

In Javadoc you have nine tags. Read on to learn more about these tags and the best practices for Java documentation using each tag.  

• @author
• @version
• @param
• @return
• @exception/@throws
• @see
• @since
• @serial/@serialField/@serialData
• @deprecated

Use @link and @linkplain for Pointing to Some Code

@link and @linkplain can be useful to refer to classes and methods if there is a dependency. In order to make it easier to navigate through methods and classes, you can use @link. It works like this: 

• {@link BurgersManager} to point to a class
• {@link BurgersManager burgers manager} to point to a class with a given label
• {@link #eat(Burger, boolean)} to point to a method inside the same class
• {@link #eat(Burger, boolean) eat} to point to a method inside the same class with a given label
• {@link BurgersManagers#eat(Burger, boolean)} to point to a method inside another class
• {@link BurgersManagers#eat(Burger, boolean) burgers manager eat} to point to a method inside another class with a given label

The difference between @link and @linkplain is that the latter one doesn’t produce a monospaced code font.

Use @code for Code Snippets

Often, you can find some code inside a Javadoc to illustrate how to use a method, class or to provide some other example. In order to display the code correctly and preventing some markup to be interpreted such as <String> and so on, you can use the @code.

 
{@code 
List burgers = new ArrayList<>();
  for(int index = 0; index < 10; index++) {
    burgers.add(new Burger(“Burger #” + index)); 
  }
}

The @code will generate the <pre> markup for you.

Use @value to Insert the Value of a Field in the Documentation

When you have a constant, you may want to display its value in the documentation. There are two options to do so: 

• Insert the value yourself. But if the value changes, you will have to update your Java documentation manually.   
• Use @value which will insert the value for you. If that value later changes, Javadocs will update that Java documentation for you.    

Using a single value using Javadocs can be really helpful, as illustrated in the example below: 

/**
 * The default value for this field is {@value}.
*/
public static final String BURGER_SHOP_NAME = "Thierry's shop";

But you can also refer to another constant, for example:

/**
 * The default value for this field is {@value} when the value 
 * of {@link #OWNER} is {@value #OWNER}.
 */
public static final String BURGER_SHOP_NAME = "Thierry's shop";

/**
 * The default owner of this awesome burger shop.
 */
public static final String OWNER = " Thierry";

Indicate When the Features Have Been Available With @since

It is often useful to indicate when a class or a method became available in your code. To implement this Javadoc, use the @since tag followed by the version/year since the feature or class has been implemented: 

/**
 * This awesome class is for doing awesome things
 * @since burger-core-0.1
 * @version 0.2
*/
public class BurgersManager {

  /**
   * Allows to eat burgers
   * @since burger-core-0.2
   */
  public void eat(Burger burger, boolean fast) {
    // TODO
  }
}

In the example above, @since is used on both methods and classes and not only with a version number. Saying that a class or a method are available since version 0.2 doesn’t have a particular meaning. Version 0.2 of what? This is why it’s essential put a relevant @since for helping my teammates understand when something has been available at first sight. 

This Javadocs tag also helps you build release notes. No, really, go to your favorite IDE, IntelliJ IDEA for instance, and search for files containing "@since burger-core-0.2" and voila you can identify what has been added. One caveat, this only shows you what’s new and not what’s updated.  

Don’t Be Anonymous, Use @author

If you write code, own it. You have the @author tag you can use to identify you’re the author of a class or method. Best practice is to use the Javadocs @author tag on both classes and methods. 

Another best practice is to put all authors for a class or method. Imagine you and your teammate have written an awesome method and you’re identified as the only author. And one day, when you are on vacation, someone is reading your wonderful method and doesn’t understand it very well and would like some details.  

But as you’re listed as the only author ,they don't know that the information is easily accessible from your colleague who worked on this code with you. Always document the code authorship with @author. 

For Non-Void Methods, Always Use @return

There’s a better way than the example below: 

/** Get the address.
 * @return
 */
public String getAddress() { /* … */ }

Instead of having the poor Java documentation like the example above, you can easily have a better version: 

/**
 * Get the address of this burger shop. The address is of the following format:
 * {@code address line 1
 * address line 2
 * zipcode city}
 * @return the address of this burger shop or {@code null} if not filled.
 */

Clarify What Parameters Mean With @param

What is more frustrating than seeing a method that takes a parameter named something unclear, like i with no documentation? Sometimes you can guess the purpose of that parameter thanks to the method's name. Then again, sometimes you cannot. So in your documentation you should use @param in order to indicate what this parameter means and, potentially, indicate what the valid values are. In our case, i could be the level of the log and the values will be INFO, DEBUG or TRACE. Another case where this tag is particularly useful is when the value corresponds to an index. In some case indexes start at 0 and in other at 1. @param is the right tag to describe such differences. 

Generating Javadocs

It’s one thing to have good Java documentation in your code, but generating it is another story.  

One option is to use the Javadoc tool in your JDK to execute something like: 

javadoc {packages|source-files} [options]

You can specify the packages, space separated, or source files, also space separated, for which you want to generate the documentation.

Here's a short description of some options javadoc utility accepts:

• -author for generating the @author tag in the generated documentation
• -d directory for generating the documentation elsewhere than in the current directory
• -nodeprecated for avoiding the generation of documentation for code marked as @deprecated
• -protected to include protected and public class and class members -private to include private class and class members
• -public to only include public class and class members

Tools such as IDEs are also able to generate your documentation but also preview it to this if it is well formatted.

Dependency management tools like Maven and Gradle also include a phase or task to generate your documentation. And this is great! Because your documentation can always be produced with the release and so it will always be up to date.

AI for Javadocs 

In some IDEs, including IntelliJ IDEA, you can use an AI assistant to automatically generate a relevant Javadoc tag for you.  

🧠 Want to learn more about using AI for Java development? Read this blog. 

Final Thoughts

Writing Java documentation is something that matters a lot for your whole team. It helps you clarify what you are coding and more importantly why you're implementing it this way. 

Want to continue writing great code — faster? Try JRebel. By eliminating redeploys you could save a month of development time annually. See how much time your team could save during your 14-day free trial.   

Improve Productivity With JRebel 

Documentation isn't the only pathway to creating efficiency in your Java development practice. By eliminating rebuilds and redeploys with JRebel, you could save a month of development time annually. See for yourself during your 14-day free trial. 

Try JRebel Free