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 ex­pla­na­tions. Doc­u­men­ta­tion 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 ex­pe­ri­enced de­vel­op­ers. Depending on the project and its scope, things can quickly become un­pre­dictable, 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 in­tu­itive­ly un­der­stand it.

In order to help avoid mis­un­der­stand­ings and structure code more clearly, Java gives users the ability to write comments. You can use comments in this pro­gram­ming language to explain your thought process, cal­cu­la­tions, methods, classes or struc­tures. 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 suf­fi­cient in­for­ma­tion. When trou­bleshoot­ing, well-for­mu­lat­ed comments are essential.

Java comments are available in three different versions: single-line comments, block comments (multi-line comments) and doc­u­men­ta­tion 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 in­for­ma­tion 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 con­sec­u­tive 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 au­to­mat­i­cal­ly 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 ex­pla­na­tions need to be a little longer, you can use multi-line comments. The­o­ret­i­cal­ly they can be of any length. They’re suitable for including al­ter­na­tive lines of code that are excluded from com­pi­la­tion or for detailed ex­pla­na­tions. Multi-line comments are in­tro­duced 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 in­tro­duc­to­ry slash and closing slash is treated as a comment and is not taken into account when compiling the code.

Doc­u­men­ta­tion comments

While single-line and multi-line comments can the­o­ret­i­cal­ly be inserted anywhere in the source code, doc­u­men­ta­tion comments are always placed directly before the classes or methods they describe. With the help of tools, these comments are read out and sum­ma­rized in HTML doc­u­men­ta­tion. They’re primarily used to create meta data for authors and certain types of pa­ra­me­ters. These are marked with an @ symbol. Doc­u­men­ta­tion comments are in­tro­duced with a slash and two asterisks (/**) and end with an asterisk and a slash (*/).

Single-line comments

To un­der­stand 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 in­struc­tions. **. 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.

Al­ter­na­tive­ly, 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 in­struc­tions in your code. Multi-line comments are always in­tro­duced with a slash and an asterisk. Here’s a multi-line comment before the code in­struc­tions:

/* 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 in­struc­tions:

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

Doc­u­men­ta­tion comments

Doc­u­men­ta­tion comments work in a similar way to block comments but are in­tro­duced by a slash and two asterisks. This allows doc­u­men­ta­tion tools to use the comments to create doc­u­men­ta­tion. 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 doc­u­men­ta­tion comments also uses other helpful tags. Here are some of the most important ones: