التعليقات

Written Explanation

The three kinds of comment

The Java Language Specification defines two kinds of comment: the traditional comment /* ... */ and the end-of-line comment // .... Javadoc comments are a special use of the traditional form. In practice you will meet three styles:

Here they all are in one program:

/**
 * Prints a one-line welcome for new students.
 * Written for the first-program lesson.
 */
public class Notes {

    /**
     * Starts the program and prints the welcome line.
     *
     * @param args command-line values (not used here)
     */
    public static void main(String[] args) {
        // Single-line comment: the compiler ignores everything after the slashes.
        System.out.println("Welcome!"); // a comment can also follow a statement

        /* A multi-line comment can
           span as many lines as you need. */
        System.out.println("// this is text, not a comment");

        // System.out.println("Not printed");
    }
}

Compile and run it. The output is:

Welcome!
// this is text, not a comment

Notice what is not printed: nothing from the comments, and nothing from the commented-out last statement.

Rules the compiler follows

From the specification:

• Everything inside a comment is ignored. It is not checked for spelling, correctness, or anything else.
• Comments are not recognised inside text in quotes. That is why "// this is text, not a comment" prints in full: the slashes are part of the string.
• A traditional comment does not nest. The first */ ends it, even if you wrote another /* inside. This makes a surprising error:

/* outer start
   /* inner */
   still outer? */

The comment ends at the first */ after the word inner. The text still outer? */ is then treated as code, and javac reports an error on it. The exact message depends on the JDK version. When you see an odd error right after a comment, look for this.

• A multi-line comment that you forget to close swallows everything after it up to the next */, or to the end of the file, which gives an error such as "unclosed comment".

Javadoc comments

A Javadoc comment starts with /**. The javadoc tool that ships with the JDK reads these comments and generates HTML documentation pages for your classes and methods. The comment is placed immediately before the declaration it describes: a class, a method, or a field. The first sentence is the summary. Lines starting with @param and @return describe parameters and return values in a structured way.

The main method above has an @param args line. Do not worry about the other tags yet. You will use @param and @return more when you write methods that take values and return results.

A Javadoc comment is still a comment, so the compiler ignores it. The difference is that a tool treats it as documentation. Use /** */ for descriptions of classes and methods, and // for notes inside method bodies.

Switching a line off

Putting // at the front of a line comments it out. The compiler skips it, but the code stays in the file. Developers do this to test the program without a statement, or to keep an old version beside a new one while experimenting. Used briefly, it is fine. Do not leave large blocks of commented-out code in finished programs: version control tools, which you will meet later, remember the old version for you, and dead code makes files harder to read.

(Most IDEs provide a shortcut that comments or uncomments the selected lines. The key combination differs by IDE and operating system, so look for "Comment with Line Comment" in your IDE's Code menu.)

When is a comment useful?

A comment is useful when it tells the reader something the code does not already say. Compare:

// print the text
System.out.println("Receipt printed");

The comment repeats the code. It adds nothing, and if someone changes the code but forgets the comment, the comment becomes a lie. Now compare:

// The printer driver needs two blank lines at the end, or the last line is cut off.
System.out.println();
System.out.println();

This comment explains why. Nobody could work that out from the two statements alone.

A short rule: explain why, not what. Good reasons to write a comment:

• A decision that is not obvious ("we print twice because the printer cuts the last line").
• A warning about a trap ("do not change this order, the report depends on it").
• A summary of what a class or method is for (this is the Javadoc comment).
• A pointer to where an unusual rule comes from (a requirement, a ticket, a document).

Bad reasons: repeating the line below, explaining syntax that the language already makes clear, or apologising for confusing code. If code needs a long comment to be understood, consider rewriting the code to be clearer, with better names and a simpler layout.

Comments also need maintenance. When the code changes, update or delete the comment. A comment that contradicts the code is worse than no comment.