DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Newsletter
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Related

  • Arrays in Java
  • Top Java Security Vulnerabilities and How to Prevent Them in Modern Java
  • Multithreading in Modern Java: Advanced Benefits and Best Practices
  • Apache Spark 3 to Apache Spark 4 Migration: What Breaks, What Improves, What's Mandatory

Trending

  • Tracing Dangerous Python Code Paths With rce-path
  • AI-Assisted Product Discovery
  • The "Just Read the Code" Myth Is Killing Your AI Workflow
  • Architecture Review Boards for Generative AI: A Framework for Governance, Risk Management, and Responsible Adoption

Draft This article hasn't been published, so readers can't see it.

In moderation This article is waiting for review, so readers can't see it yet.

Deleted This article has been deleted, so readers can't see it.

  1. DZone
  2. Coding
  3. Java
  4. Increase Your Code Quality in Java by Exploring the Power of Javadoc

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

Learn to improve your Java Code documentation using the power of Javadoc.

By 
Otavio Santana
DZone Core CORE ·
Feb. 16, 23 · Tutorial
Post on X (opens in a new tab) Share on LinkedIn (opens in a new tab)
7.7K Views

Join the DZone community Save articles, join the discussion, and download Refcards and Trend Reports with a free account.

Join for free Already a member? Log in

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:

Java
 
/**
 * 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.

Java
 
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


Documentation Javadoc Java (programming language) Data Types

Opinions expressed by DZone contributors are their own.

Related

  • Arrays in Java
  • Top Java Security Vulnerabilities and How to Prevent Them in Modern Java
  • Multithreading in Modern Java: Advanced Benefits and Best Practices
  • Apache Spark 3 to Apache Spark 4 Migration: What Breaks, What Improves, What's Mandatory

Partner Resources

×

Comments

Loading comments

The comments didn't load

Please try again in a moment.

Likes

Loading

The next likes didn't load. Please try again.

The likes didn't load

Please try again in a moment.

See who liked this

Log in or join DZone for free to see who liked this article.

Log in Join for free
  • RSS
  • X
  • Facebook

ABOUT US

  • About DZone
  • Support and feedback
  • Community research

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 215
  • Nashville, TN 37211
  • [email protected]

Let's be friends:

  • RSS
  • X
  • Facebook