Commenting Java Code

Why Do We Need Comments?

As you write more complex programs, you'll find it's easy to forget why you wrote a certain piece of code a particular way. Comments serve as a form of in-code documentation. They can explain the purpose of a tricky algorithm, leave a reminder to fix something later, or simply make the code easier for another person (or your future self) to understand.

Another powerful use for comments is to temporarily "turn off" lines of code without deleting them. This is a common practice when debugging or testing different approaches.

To start, let's watch a short video from Giraffe Academy that introduces the core idea behind comments.

Types of Comments in Java

Java provides two primary ways to write comments. Let's look at each one.

The W3Schools page on Java comments offers a very clear and direct explanation of the syntax for both types.

To summarize what you've just read:

1. Single-Line Comments: These start with two forward slashes // and continue to the end of the line. They are perfect for brief notes.

   // This is a single-line comment.
   System.out.println("Hello, World!"); // This is also a single-line comment.
   

2. Multi-line Comments: These start with /* and end with */. They can span multiple lines and are ideal for longer explanations.

   /*
     This is a multi-line comment.
     It can be used to write detailed descriptions
     of a class or method.
   */
   public class MyProgram {
       // ...
   }
   

Practical Application: Commenting Out Code

One of the most frequent uses for comments during development is to temporarily disable code. This is much safer than deleting it, as you can easily bring it back.

Let's say you have the following code from our last lesson's practice exercise:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
        System.out.println("Hello, World!");
        System.out.println("Hello, World!");
    }
}

If you wanted to see what happens when you only print the message once, you could "comment out" the other two lines:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
        // System.out.println("Hello, World!");
        // System.out.println("Hello, World!");
    }
}

Now, when you run the program, the compiler will ignore the commented-out lines, and you'll only see "Hello, World!" printed once.

This technique is incredibly useful for isolating problems or testing changes. The following clip from the Giraffe Academy video demonstrates this exact use case.

A Programmer's Best Friend: The Comment Shortcut

Manually typing // at the beginning of every line you want to comment out would be tedious. Thankfully, your IDE, IntelliJ IDEA, has a powerful shortcut for this.

You can comment or uncomment a single line (or a whole block of selected lines) by pressing Ctrl + / on Windows/Linux or Cmd + / on macOS.

The following video from Alex Lee's channel clearly demonstrates this shortcut.

The image below illustrates exactly what this looks like in an editor. A block of code has been selected, and the shortcut has been used to place // at the start of each line, effectively disabling the entire block.

Practice Time

Now it's your turn to put this into practice.

1. Open the HelloWorld project you created in the last lesson.
2. At the very top of the HelloWorld.java file, before the public class HelloWorld { line, add a multi-line comment that includes your name, today's date, and a brief description of what the program does.
3. Above the System.out.println("Hello, World!"); line, add a single-line comment that explains what that line of code does.
4. If you still have the ten System.out.println lines from the previous lesson's practice, select five of them and use the Ctrl + / (or Cmd + /) shortcut to comment them out.
5. Run your program. You should see "Hello, World!" printed only five times.
6. Now, select the same five commented lines and use the shortcut again to uncomment them. Run the program to confirm all ten lines are working again.

Conclusion

In this lesson, you've learned a fundamental skill for writing clean and maintainable code. Documenting your work and knowing how to test it by commenting out sections are practices you will use throughout your entire programming career.

Here are the key takeaways:

• Comments are notes for human readers that are ignored by the Java compiler.
• Single-line comments begin with //.
• Multi-line comments are enclosed between /* and */.
• A primary use of comments is to explain the "why" behind your code.
• Commenting is also a vital tool for debugging by temporarily disabling code.
• Modern IDEs provide a shortcut (Ctrl + / or Cmd + /) to quickly comment and uncomment lines of code.

You have now completed the first module on Java fundamentals! You know what Java is, how to set up your environment, the basic structure of a program, how to print output, and how to document your code.

In our next lesson, we will begin the second module and start making our programs much more interesting by introducing variables. You will learn how to declare and use variables to store and manipulate data like numbers, text, and true/false values.