Java Comments

In the previous tutorial, you wrote your first Java program. Now, let’s dive into an important aspect of programming: Java comments.

What Are Comments? #

Comments are special annotations we add to our code to make it more understandable. Java comments are not executed or processed by the compiler, meaning they don’t impact the program’s functionality. They are purely for the benefit of the programmer, making the code easier to read and maintain.

For example:

class HelloWorld {
    public static void main(String[] args) {
        // print Hello World to the screen
        System.out.println("Hello World");
    }
}

Here, // print Hello World to the screen is a single-line comment. The Java compiler ignores this line entirely, allowing us to add helpful notes to the code.

Types of Comments in Java #

Java provides three types of comments:

1. Single-line Comments
2. Multi-line Comments
3. Javadoc Comments (which we’ll explore in future tutorials)

1. Single-line Comment #

Single-line comments are used for brief explanations or notes on a single line. You can add a single-line comment by starting the line with //. Everything following // on that line is treated as a comment by the compiler.

Example:

// declare and initialize two variables
int a = 1;
int b = 3;
 
// print the output
System.out.println("This is output");

In this example, the comments explain the two key steps in the code: declaring variables and printing output.

2. Multi-line Comment #

If you need to write comments over multiple lines, you can use the multi-line comment format. This starts with /* and ends with */. Everything in between is considered a comment, no matter how many lines it spans.

Example:

/* This is an example of a multi-line comment.
 * The program prints "Hello, World!" to the standard output.
 */
class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

Here, the comment spans multiple lines, making it useful for longer explanations or to temporarily disable large blocks of code.

3. Prevent Executing Code Using Comments #

You can also use comments to “disable” certain parts of your code temporarily. This can be useful for debugging or testing when you want to isolate a piece of code without removing it.

Example:

public class Main {
    public static void main(String[] args) {
        System.out.println("some code");
        // System.out.println("error code"); // Disable this line during debugging
        System.out.println("some other code");
    }
}

In this example, the second println is commented out, so it won’t execute. You can easily re-enable it by removing the //.

Why Use Comments? #

Here are some reasons to use comments in your Java programs:

• Improve Code Readability: Comments help explain your logic, making your code easier to understand for future developers (or for yourself, when you revisit the code).
• Debugging Tool: Comments allow you to temporarily disable sections of code without deleting them, which is helpful during debugging.
• Collaboration: When working in teams, comments make it easier for other developers to understand your code.

Best Practices for Writing Comments #

While comments are helpful, they should not be overused or used to explain poorly written code. Here are some best practices:

• Write clean and understandable code first. Use comments as a supplement, not a replacement.
• Focus on explaining the “why” rather than the “how”. For example, instead of commenting on every line of code explaining how it works, explain why you made a certain design decision.
• Keep comments concise and relevant. Avoid unnecessary comments like // increment i by 1 if the code is already self-explanatory.

Why Use Comments? #

Here are some reasons to use comments in your Java programs:

• Improve Code Readability: Comments help explain your logic, making your code easier to understand for future developers (or for yourself, when you revisit the code).
• Debugging Tool: Comments allow you to temporarily disable sections of code without deleting them, which is helpful during debugging.
• Collaboration: When working in teams, comments make it easier for other developers to understand your code.

Best Practices for Writing Comments #

While comments are helpful, they should not be overused or used to explain poorly written code. Here are some best practices:

• Write clean and understandable code first. Use comments as a supplement, not a replacement.
• Focus on explaining the “why” rather than the “how”. For example, instead of commenting on every line of code explaining how it works, explain why you made a certain design decision.
• Keep comments concise and relevant. Avoid unnecessary comments like // increment i by 1 if the code is already self-explanatory.

Want to learn Java Programming with an instructor, either offline or online? Find experienced tutors near you and join Coaching Wallah.