In this post I would be discussing comments in a Java program. A comment allows us to insert text that will not be compiled nor interpreted. It can appear anywhere in the source code where whitespaces are allowed. The primary purpose of comment(s) is to leave a note for ourselves related with the code. It is a sort of documentation within the code itself.

Comments are sometimes also use to prevent a portion of code from executing. This acts like a quick debugging tool. The idea is to disable a certain piece of code without actually removing it.

Java language supports three types of comments, viz. single line comments, multiple line comments and documentation comments.

Single line comments begin with double forward slashes and continue up to the end of line.

//this is a single line comment

c=a+b; // this is also a single line comment

Multi-line comments begin with a slash asterisk combination and end with an asterisk slash combination. Multi-line comments cannot be nested, that is, we cannot have a comment within a comment. Nested multi-line comments are not allowed because */ of the second comment would mark the closing comment and the remaining portion would result in an error.

/*this is 
a multi-line line 
comment*/

/*a=2;
b=3;c=a+b;*/

Documentation comments are used in conjunction with javadoc tool. Documentation comment (or doc comment) begin with /** and end with */. Usually, doc comment are not explained in most of the ICSE/ISC books. It’s very simple to understand doc comments if we are using BlueJ. Just create a class using any name and pay attention to the code which is present by default. The default code is as follows:

/**
 * Write a description of class CommentDemo here.
 * 
 * @author (your name) 
 * @version (a version number or a date)
 */
public class CommentDemo
{
    // instance variables - replace the example below with your own
    private int x;

    /**
     * Constructor for objects of class CommentDemo
     */
    public CommentDemo()
    {
        // initialise instance variables
        x = 0;
    }

    /**
     * An example of a method - replace this comment with your own
     * 
     * @param  y   a sample parameter for a method
     * @return     the sum of x and y 
     */
    public int sampleMethod(int y)
    {
        // put your code here
        return x + y;
    }
}

The comments before the class and the function definition are doc comments (notice /** and */). Parameters are specified by @ sign. Now click on the drop down at the top right corner of the editor as shown in the following picture.
This would result in an elegant html page documenting the class and the function. You can notice that the content is nothing but the text and parameters provided inside doc comments.

Students normally assume that anything can be enclosed with comments and whatever is enclosed is completely ignored. However, this is not true. An exception to this rule is “The compiler translates Unicode escapes into the characters they represent before it parses a program into tokens before discarding comments and white space”. This implies that if we give a wrong or non-existent Unicode escape sequence it would result in an error. Let us understand this with the help of an example, the following code:

// \user

would result in the error “illegal unicode escape” error because \user is not a valid Unicode escape sequence!