Javadoc — Software Documentation

Writing a clean code is not enough in order to build a clean code base, also a clean documentation is required to achieve a clean code base.

Good documentation is essential for the readability of the code and also it is a must-have in order to operate and maintain the code in an efficient way. As remote working is a favorite way of working nowadays and collaboration with in high number of colleagues is really required today, documenting the code is also required.

So, what is a good code base documentation? From my point of view and from my experience, a good documentation should have;

• A crystal clear expression and an easy language while documenting
• Each class, method, field should be described not with as much as detail it should have, they must be detailed.
• Reference & linking between components should be used in order to increase the readability.
• Documentation should be kept up-to-date all the time in order to preserve consistency.
• Documentation must be done easily within the code.
• Software document must be generated easily and it should be easy to understand for everyone and for every level of developer.

---

I will cover Javadoc in this article for software documentation. All LTS (long time support) JDK versions support Javadoc. Javadoc is generated from Javadoc comments which are similar to regular comment blocks in Java.

I have already added Javadoc comments to all class, methods, fields in my open-source Spring Boot example project. You can reach this project from spring-boot-project-example repo in my Github profile.

Please check the Gist to see the Javadoc example code snippet.

As seen in the example code snippet, Javadoc comment is similar to regular comment blocks in Java, except an extra asterisk while starting the Javadoc comment.

Below screenshot is from the generated Javadoc of the method specified in the above code snippet.

Javadoc can be written for class level, method level and field level. Generally, most detailed comments are for method levels in order to make crystal clear how the method is working for everyone. Field level Javadoc comments generally include a basic information about the field.

You can give external links within Javadoc comments with HTML href attribute. Generally, I use this one when linking my Github profile with my name in the author block tag. You can check the above code snippet how it is used.

Javadoc comments can be detailed with block tags and good Javadoc comments should include these block tags from my point of view.

---

Now, let’s go deep dive in block tags in Javadoc comments.

• @author → the name of the author who added the class, method, field
• @deprecated → explains why that code part is deprecated and also alternatives may be given instead of the deprecated part.
• @link → provides an inline link to a part of the code base. You can give a link to a class or even to a method or an attribute of an class. You can check below text snippet for different usages of link block tag. You can also find these within the spring-boot-project-example repo.

Please check the Gist to see the Javadoc example code snippet.

• @param → provides the details of the method’s parameter
• @return → provides the details of the method returns
• @see → generates reference sub-sections
• @since → indicates the version when the class, method, field is added to the project
• @throws → indicates that an exception can be thrown and the details of the exception
• @version → indicates the version of the project

---

In order to generate the Javadoc, we can use command line with “javadoc” command or we can use Javadoc maven plugin or we can use our favorite IDE to generate the Javadoc.

We can use the below command line in order to generate our Javadoc via command line. This will create a folder called documentation (with the -d flag) and scan all files under src folder to generate the Javadoc.

---

For Javadoc Maven dependency, we need to add the Maven Javadoc plugin in the pom.xml as below;

Then, below command should be executed in the base directory of the project.

---

Javadoc can be generated from the IDE that you use. I am using IntelliJ IDEA and Javadoc generation is so easy from “Tools → Generate Javadoc…” section within IntelliJ IDEA.

---

In a Nutshell

Documentation is not a nice-to-have for our software project, it is a must-have. Even, it is not enough to have documentation for the project, also the documentation should be clear, easy to be read and should have details related to the project.

Documentation makes life easier for readability of the code base, makes it easy to maintain the code base.

Your comments & questions are always welcomed.