Javadoc

Hello! In this article, i will discuss javadocs as well as some tips on writing javadocs.

JavaDocs

Javadoc is a documentation generation system, which reads comments in the source and generates compiled documentation in the form of HTML5.

Why use javadocs?

  • Improved understanding of the general structure of the project
  • help coworkers understand the complicated code
  • easy to generate

How to write a javadocs

With the help of Intellij, you could easily just type /** and press enter:

/**

Intellij just auto-generates the javadocs comments like this:

    /**
     * 
     *
     *  
     */

If you have a return type, parameters, and throw exceptions, IntelliJ also auto-generates for you.

    /**
     * Returns a newly generated id
     * @param a
     * @return a generated id
     * @throws Exception
     */
    public Long example(Long a) throws Exception {
        newId += 1;
        return newId;
    }

In the beginning, it is best to describe what the method returns. You could understand a lot if you understand what returns.

This method is fairly simple, but imagine a complicated, legacy method in which there are many parameters and returns unreadable numbers. It will save a lot of time for developers if you have a javadocs that explains what the method does and returns.

advice for writing javadocs

  • The goal is to understand the code within a few seconds
  • The javadocs class must explain the goal and responsibilities
  • The javadocs method must explain parameters and what it returns
    • do not include explanations for implementations
    • briefly explain what exception is thrown
  • Try to avoid any comments inside the code

Conclusion

In this post, i included what a javadocs is and some tips on writing javadocs.

Reference