Increase Your Code Quality in Java by Exploring the Power of Javadoc

There is certainty about how documentation increases the quality of any software. We can see it on several successful projects, such as the most used in the industry as Java, Go, Apache Cassandra, and so on. But the question is how to use it. What should and should not be on the documentation? In this article, we'll explain what you might document using JavaDoc resources, making your life easier.

Javadoc

Javadoc is the documentation generator that has been on Java since its origin. As a C/C++ developer, you might know the basics, such as putting a single-line comment and several lines of words. Using Javadoc, you can do even more. Javadoc allows us to use tags:

• @author: You can define who created this class, package, or method

• @since: specify when a feature or method was added

• @version: the current version

• @param: given a method or a constructor, the argument information

• @return: given a method a description about what is returning

• @throws: what can go wrong on this call? It is a tag to explain it so the user can avoid it. 

• @see: to get more information on another method.

Those tags are beneficial, mainly because the final result of a JavaDoc is an HTML page, where you can see this information as a Link page or a description on the page.

This session introduced a brief overview of Javadoc. Hopefully, I proved to you that it is more potent than C/C++ documentation. You can use these tags to better illustrate the documentation that Javadoc will generate in HTML. Let's go to do code. Let's start with the hard one — what not to document.

What To Avoid in a Documentation

For me, the art of saying "no" is problematic. However, we should put it into practice first because more documentation also means more points to update and maintain. Another point is the noise effect; as much information you place, it might cause a negative impact, so the user might ignore it. 

Avoid explaining the Java syntax on Javadoc; please, let it be in the Java tutorials and articles. Don't use Javadoc to explain the Java structure, Java methods, and so on. The code sample below is a sample of what you should not do:

/**
 * This is a class
 */
public class Animal {

    /**
     * This is a field
     */
    private String name;

    /**
     * This is a constructor
     * @param name
     */
    public Animal(String name) {
        this.name = name;
    }


    /**
     * This is a getter
     * @return
     */
    public String name() {
        return name;
    }
}

Avoiding unnecessary noise on the documentation is the first big step, the thing about how worth this information is, so put it. Let's move to the next session, where we can deeply explore it.

Good Documentation With JavaDoc

Starting with the no, the hard part for me, let's talk about what we can include on the Javadoc. In regular software (a non-framework, specification, or any Dev-experience tool), we might have two good options:

• Why: The reason for that code decision. E.g., a description of the decision and an explanation.

• Business perspective: The domain is what matters for software, put an explanation to make the code closer to the ubiquitous language is always a good use of JavaDoc.

Let's imagine the FIFA scenario, where we need to create a team; we can put why we're using records and some rules and validation around the FIFA championship. As you can see, not all methods have documentation; that is fine. Please, choose carefully what put documentation and where to call attention to the user.

public record Team(String name, List<Player> players) {

    private static final int TEAM_SIZE = 11;

    /**
     * Once, we don't change the team during the championship, we'll create using record to make it immutable.
     *
     * @param name the team's name that is valid to FIFA
     * @param players the players of the time that should not be higher the eleven.
     * @throws NullPointerException when name or players are null
     * @throws IllegalArgumentException when it has more than eleven players
     * @deprecated please use {@link Team#of(String)} instead
     */
    public Team{
        Objects.requireNonNull(name, "name is required");
        Objects.requireNonNull(players, "players is required");
    }

    /**
     * Create an empty team
     * @param name the team's name.
     * @return a {@link Team} instance
     */
    public static Team of(String name) {
        return new Team(Objects.requireNonNull(name, "name is required")
                , new ArrayList<>());
    }


    @Override
    public List<Player> players() {
        return Collections.unmodifiableList(players);
    }

    /**
     * Add a new {@link Player} on the team
     * @param player the player
     * @throws NullPointerException when player is null
     * @throws OverTeamException when it has more than eleven players.
     */
    public void add(Player player) {
        Objects.requireNonNull(player, "player is required");
        if(this.players.size() == TEAM_SIZE) {
            throw new OverTeamException("We don't support one more player");
        }
        this.players.add(player);

    }
    public boolean isEmpty() {
        return this.players.isEmpty();
    }

    public int score() {
        return players.stream().mapToInt(Player::score)
                .sum();
    }
}

This video brings several topics to increase your Java documentation by JavaDoc:d