2.3 - Comments

Comments are sections of plain-text used to explain code and do not affect the program. Anything written inside a comment is ignored by the compiler and will never be executed. Java has two ways to make comments. While the naming can vary, they are usually called single-line and multi-line comments.

Single-Line Comments

A single-line comment, sometimes called inline comment or end-of-line comment, applies to only one line, beginning with two forward slashes: //. All text to the right of the // is ignored. Single-line comments end with the end of the line. It can appear on a line by itself, or at the end of a line after some code.

For example,

public static void main(String[] args) {
    System.out.println("hello world"); // output-text
    System.out.println("goodbye"); // output more text
}

In the code above, // output text is a comment.

If the code was instead:

public static void main(String[] args) {
    // System.out.println("hello world");
    System.out.println("goodbye");
}

Here, "goodbye" would be printed, but "hello world" would not be. This is because all code to the right of the // is ignored. Code is commented-off when it could be executed, but is placed inside a comment to prevent it from executing. You may occasionally do this when debugging to temporarily "remove" the code, and can uncomment it later.

Multi-Line Comments

A Multi-Line comment, sometimes called a block comment, can span multiple lines and begins with a /* and ends with */. All text between the /* and */ is ignored. Generally when spanning multiple lines, redundant asterisks are used to line up the text. 

public static void main(String[] args) {
    /*
     * This is a multi-line (block) comment
     *
     * Nothing in here is executed
     * System.out.println("this won't print");
     */
    System.out.println("this will print");

    /*
        This is also a multi-line (block) comment.
        Asterisks (*) are not needed in the middle
        They are only needed at the start and the very end.

        Without them, it is harder to figure out where to line
        something up.
     */
    System.out.println("this will also print");
}

It is also possible to comment off a specific section of a single line. This is considered bad practice since it can be very difficult to red, such as the following comment examples: 

public static void main(String[] args) {
    /* bad comment */ System.out.println("this will print");
    System.out.println(/* bad comment */ "this will also print");
}

You will sometimes see a "multi-line comment" being used as a "single-line comment": 

public static void main(String[] args) {
    /* This is a comment */
    System.out.println("this will print");
}

Javadoc Comments

There is a special type of multi-line comment, called a Javadoc comment. A Javadoc comment is a specifically formatted multi-line comment that can additionally be used to generate documentation. The javadoc tool can generate HTML documentation from the comments. Thus, the comment is ignored by Java's execution, but not by the javadoc tool.

Javadoc comments start with /**, and end with */.

An example of the generated HTML documentation can be found here.

An example javadoc comment is shown below:

    /**
     * Prints a String and then terminates the line.  This method behaves as
     * though it invokes {@link #print(String)} and then
     * {@link #print()}.
     *
     * @param x  The {@code String} to be printed.
     */
    public void println(String x) {
        ...
    }

Many of the features you can do with javadoc are beyond the scope of this chapter. We will revisit them in %chapter #%.

TODO Comments

A TODO comment indicates that you will come back to fix that code later. It is created by adding TODO (case-insensitive) inside any other type of comment. These are quite handy when you're already in the middle of developing a feature and realize something else that needs fixed, but you don't have the time to fix it right now. Once it is fixed, delete the TODO comment.

For example, you might add this TODO comment:

public static void main(String[] args) {
    // TODO sort them alphabetically
    System.out.println("Bob, Alice");
}

Viewing TODOs in IntelliJ

Many editors have a way to view all the TODO comments. With the default IntelliJ layout, TODO comments can be found in a tab on the bottom-left of the window. The following image shows an example.

image info

IntelliJ Shortcuts

To comment (or uncomment) the current line, press CTRL + /. This moves the caret down a line.

To comment (or uncomment) multiple lines, highlight the region, then press CTRL + /.

Good Practices