Best Practices for Code Documentation in Java

Code documentation is a necessary evil that every developer has to deal with. Almost every programming language has different ways of approaching code documentation, and today, we will discuss the best practices of code documentation in Java. With Java, anyone can easily create enterprise-level applications. It is object-oriented in nature and is suited for developing any modern web application. Not to mention it can also be used in creating web apps, games, desktop applications, mobile applications, etc.

There are many ways of approaching code documentation in Java, but they do have a caveat. Not every approach can be equated to good practice, but that doesn’t mean you cannot work with anything besides best practices. Feel free to change the paradigm if your project needs it.

Documenting your code is a fun process. Check out hvlmnns from Munich, Germany creating Temple, a PHP language engine, and its documentation.

Code Documentation — A Debate

Before we move on to the specificities of Java code documentation, let’s look at the current state of code documentation in the industry. You can find two types of people: one religiously defending how amazing their application is and why they don’t need to comment their code, and the other who understands the importance of code documentation. The first type thinks if you write good enough code, you don’t need to comment it. That’s partly true, but doesn’t show the complete picture.

Even though it feels awesome to think that your code doesn’t require any code documentation, it is not practical at all. Many times, programmers have to write code for complex business logic. Without code documentation, it is hard to understand the logic behind the code.

In short, it is important to understand that code documentation is required, but not always necessary. It depends on what type of code you are writing. And, yes, you don’t need to comment a simple method that outputs, “Hello, World!”

Let’s discuss the best practices of code documentation in Java.

1. Three Types of Comments

Java comes with the support of three types of comments. Java programmers widely use the first two types, //, and /* */. Both of them are useful, but they don’t work with the revolutionary idea of JavaDoc.

The JavaDoc utility program enables you to extract code comments into external HTML files. This utility is one of the best features of the Java Development Kit (JDK) and helps coders to easily create code documentation. If you have ever seen the Java API library, you already know how they make use of code documentation.

To make use of the JavaDoc utility, you need to use the third type of comment  /** */.

So, how does it work?

The JavaDoc functionality works with the help of tags. You can customize your comment using any tag provided by the utility. For example, you can use @author tag to identify the author of a class, @exception to showcase the exception thrown by a method, and so on. You can find the full list here.

Example 1:

/**

* The class helps listens to the user request

* And output

* @version 8.9

* @author Nitish Singh

*/

As you can see, the comment starts with /** and ends with  */.

JavaDoc utility helps you export the code comments into the HTML format. If you want to convert it to other formats, you need to use Pandoc for quickly converting one format to another. You can also check out the 10 best tools for perfect code documentation here.

2. Always Document API

Application Programming Interface (API) helps connect software across different platforms. APIs are made for other people to use, and that’s why they should be documented. Before you start documenting your API, you need to understand the value of simplicity and conciseness. Always try to keep the two factors in check, as it will help you write great API documentation or documentation in general.

This point is well explained in a blog article, “The Golden Rules of Code Documentation.” You can check it out by clicking here.

3. Revisit the Code Documentation

Code documentation can change shape over the timespan of a project. It is necessary to understand that when code evolves, the code documentation also evolves. So if you start writing code documentation too early, you will have to change it often. If you want to get a hold of the process of code documentation, it is a good idea to start late!

4. Use DocCheck to Your Advantage

The Doc Comment Checking Tool (DocCheck) is a great tool to check your code comments. It runs over your source code and generates a simple report with all the tag and style errors. The tool will also help you to fix the issues, with recommended changes. To make use of the plug-in, you need to install it along with the JavaDoc tool.

5. Give Meaning to Your Code Documentation

Code documentation is the key to making others understand what you have done. The code can be self-explanatory, but you need to make it meaningful. And that is why you should always try to answer the “Why” and let the code explain the “How.”

6. Always Mention Implementation-Independence

When writing API code documentation in Java, you, as a developer, need to take care of the implementation on different platforms. Try to cover different angles that make the API work and cover extreme cases as well. The approach should always be clear and make proper use of the available tags.

7. Method Comments Can Be Automatically Re-Used

JavaDoc works in a very structured way. It inherits all the comments for methods which are either an implementation over other methods or is overridden. The automatic behavior can help you avoid retyping, and make the proper use of JavaDoc tool.

Conclusion

Code documentation optimization is a deep topic, and would require introspection from different levels. Java official documentation page provides an excellent tutorial on how to write doc comments for the JavaDoc tool. You can find it here.

So what practices do you follow when documenting in Java? Let us know in the comments section below.