How to Write Comments in Java

When you’re coding, the first thing on your mind will be how the computer processes the code you write. However, it’s also essential to think about how people will read your code.

Whether you’re working on a project with a team, or are just building something yourself, you should take steps to document your code adequately.. That’s where comments come in.

A comment is a line or multiple lines of text written in a program that is ignored by the computer. Comments are used to explain the intent of a program to humans who may be reading your code, whether that’s yourself or someone else.

This tutorial will discuss how to write comments in Java and walk through a few best practices you can use to write effective comments.

Java Comments

If you are new to programming, you may ask yourself: why should you comment code? There are a couple of reasons why code comments are important to write.

When you’re writing code, it is important to acknowledge that your code will be read by someone, even if that someone is you. Further, there is no guarantee that the person reading your code will understand the code you have written.

If you’re working alone, having code without comments may feel frustrating and cause you to spend time figuring out how your code works. But if you’re working on a team, having no comments can be even more disruptive. Other developers may have to ask you about your code, which can consume valuable time.

Overall, writing comments makes code easier to read. When you’re writing a complex procedure, it can be helpful to have some plain text next to your code to explain your intent behind certain lines of code. The comments you write will be useful for future reference, especially if you’re working with other developers on a project.

The best comments explain the intent behind your code. Why did you do something in a particular way, rather than reiterating what a line of code does? Effective comments answer questions and improve efficiency.

Java Comment Syntax

In Java, there are two types of doc comments which can be written: single-line comments and multi-line comments.

Single-Line Comments

Single-line comments, often called inline comments, appear at the end of a line of code.

Inline comments are typically used to annotate small parts of code which last one or so lines. 

Suppose we are writing a program that prints out the message It’s Friday to the console. We want to write a comment to keep track of our code. Here’s an example of an inline comment we could use:

public class FridayMessage {
	public static void main(String[] args) {
		System.out.println("It's Friday!"); // prints "It's Friday" to the console
	}
}

Inline comments should only be used when you need to explain your intent behind a specific line of code. Code that includes a large number of inline comments can quickly become difficult to read.

It’s important to note that, when you’re writing comments, your goal should be to explain the intent behind your comments. In our above example, our comment was not very useful because it is easy to tell what our code does. But if we had a more complex line of code, a comment may be needed.

Multi-Line Comments

Multi-line comments, also known as block comments, are comments that are used to explain a section of code. Multi-line comments will last multiple lines and are usually placed at the top of a file or before a block of code starts.

Multi-line comments start with /* and end with */. Here’s an example of a multi-line comment in a Java source file:

/* This is an example multi-line comment.

    The code below prints out It’s Friday! to the console.

*/

public class FridayMessage {
	public static void main(String[[ args) {
		System.out.println("It's Friday!");
	}
}

In this example, our comments appear on the first three lines of our code.

Often, multi-line comments will be used at the start of a file to note details about the file itself. For instance, a multi-line comment may include information about the author of a file, the file’s version, and similar information.

Commenting Code for Testing

In addition to serving as a method of documentation, comments are also used to prevent code from executing during the testing and debugging phases of software development. Coders refer to this as commenting out code.

Suppose you are writing a program that has raised an exception. You are not sure what is wrong yet, and so you want to comment out part of your code to help you figure out the source of the problem. Here’s an example of comments being used to comment out a line of code:

class FridayMessage {
	public static void main(String[[ args) {
		String day_of_the_week = "Friday";
		// System.out.println("It's " ++ day_of_the_week);
	}
}

In this example, we have commented out the line of code starting with System.out.println. Our code returned an error (because we used two ++ instead of one) and we commented out the code while we figured out the source of the error.

Commenting out code can be especially helpful when you’re analyzing the logic of a program. In these situations, you may want to comment out multiple iterations of your code until you find the most efficient one. After that point, you can remove your old code.

You should only comment code out during the testing and debugging phases. Leaving commented out code in a final program can be confusing for other developers and also makes code more difficult to read.

"Career Karma entered my life when I needed it most and quickly helped me match with a bootcamp. Two months after graduating, I found my dream job that aligned with my values and goals in life!"

Venus, Software Engineer at Rockbot

Find Your Bootcamp Match

Conclusion

In Java, there are two types of comments: single-line (or inline) comments and multi-line (or block) comments. These comments are used to document your code and can also be used to assist you during the testing and debugging phases of software development.

Taking time to comment on your code will make your work more readable for both yourself and anyone else who may be reading your code. And finally, remember that the best comments are those that explain the intent behind your code.

Now you’re ready to start writing comments in Java like a pro!