What are Java comments and how to create them

There are three different types of comments in Java. You can use comments to structure and explain your code. Single-line comments are for short notes, while block comments are suitable for longer explanations. Documentation comments on the other hand are extensive and offer value above and beyond the source code.

What are Java comments?

Working in source code can sometimes pose problems, even for experienced developers. Depending on the project and its scope, things can quickly become unpredictable, and the code can become confusing. In moments like these, you may not want to work on your code alone. But even if you want others to be able to access your code, they may not be able to intuitively understand it.

In order to help avoid misunderstandings and structure code more clearly, Java gives users the ability to write comments. You can use comments in this programming language to explain your thought process, calculations, methods, classes or structures. When you or someone else looks at the code later, the comments will make working with the code easier.

To ensure that comments are effective, it’s important to keep them as short as possible. At the same time, they should provide readers with sufficient information. When troubleshooting, well-formulated comments are essential.

Java comments are available in three different versions: single-line comments, block comments (multi-line comments) and documentation comments. All comments are marked off so they’re not taken into account when compiling. In the following sections, we’ll show you how to create Java comments and when to use each one.

What types of comments are there in Java?

Depending on the kind of information you want to write, there are three different kinds of comments available in Java. These are:

Single-line comments

This is the simplest comment option. This type of comment is created using two consecutive slashes (//) and can’t be longer than one line. With single-line comments, you don’t need to indicate an end point since this is automatically reached at the end of the line. These type of Java comments are suitable for short comments that explain a function in a few words.

Multi-line comments

If your explanations need to be a little longer, you can use multi-line comments. Theoretically they can be of any length. They’re suitable for including alternative lines of code that are excluded from compilation or for detailed explanations. Multi-line comments are introduced with a slash and an asterisk (/*). When you reach the end of the comment, you just need to type an asterisk followed by a slash (*/). The text between the introductory slash and closing slash is treated as a comment and is not taken into account when compiling the code.

Documentation comments

While single-line and multi-line comments can theoretically be inserted anywhere in the source code, documentation comments are always placed directly before the classes or methods they describe. With the help of tools, these comments are read out and summarised in HTML documentation. They’re primarily used to create meta data for authors and certain types of parameters. These are marked with an @ symbol. Documentation comments are introduced with a slash and two asterisks (/**) and end with an asterisk and a slash (*/).

Single-line comments

To understand how Java comments work in practice, we’ll look at a few simple examples. You can try these out yourself to test the output. A single-line comment starts with two slashes and can either be on its own line or placed after a set of instructions. **. Here’s what the comment looks like on its own line:

// Example of a single-line comment
class Main {
	public static void main(String[] args) {
	// Here is the comment
	System.out.println("This is the text that will be output at the end.");
	}
}

If you use the Java command System.out.println, only the sentence ‘This is the text that is output at the end’ will be displayed. The two comments will only appear in the source code.

Alternatively, you can place the comment directly after the command:

// Example of a single-line comment
class Main {
public static void main(String[] args) {
System.out.println("This is the text that is output at the end."); // This is the comment.
	}
}

The placement of the comment does not change what is output.

Multi-line comments

If you want to insert a multi-line comment in your code, you can include it before or after the instructions in your code. Multi-line comments are always introduced with a slash and an asterisk. Here’s a multi-line comment before the code instructions:

/* In this example there is a multi-line comment.
It starts after the asterisk.
The actual instructions for the computer are under the comment.
This is the last line of this Java comment.
*/
class Main {
public static void main(String[] args) {
System.out.println("This is the text that will be output at the end.");
	}
}

The output reads “This is the text that will be output at the end.”.

Here’s how to insert the comment under the instructions:

// Example of a multi-line comment below the instructions
class Main {
public static void main(String[] args) {
System.out.println("This is the text that will be output at the end.");
/* In this example there is a multi-line comment.
It starts after the asterisk.
The actual instructions for the computer are above the comment.
This is the last line of this Java comment. */
	}
}

The output should be the same as in the previous example. The single-line comment in the first line of the code snippet will not be output either. You can place the asterisk and slash directly after the comment or use a separate line.

Documentation comments

Documentation comments work in a similar way to block comments but are introduced by a slash and two asterisks. This allows documentation tools to use the comments to create documentation. If necessary, they can also contain HTML tags such as <h1>, <p> or <strong>.

Javadoc, a popular tool that you can use to read out documentation comments also uses other helpful tags. Here are some of the most important ones: