Java Comments

In Java, comments are lines of code that are ignored by the compiler and interpreter. They are used to add explanatory notes or annotations within the program’s code. These comments do not affect the execution of the program

Why do we use comments in a code?

  • Comments in Java serve the purpose of enhancing the code’s readability by providing additional details.
  • They facilitate code maintenance and aid in the identification of errors.
  • Comments can be utilized to offer information or explanations about variables, methods, classes, or statements.
  • They can also be employed to temporarily disable the execution of specific code sections while testing alternative code.

Types of Java Comments

There are three types of comments in Java.

  1. Single Line Comment
  2. Multi-Line Comment
  3. Documentation Comment

1) Java Single Line Comment

In Java, the single-line comment is employed to comment out a single line of code. It is a widely used and straightforward method for adding comments to statements.

To create a single-line comment, two forward slashes (//) are placed at the beginning of the line. Any text appearing after the // is not executed by the Java compiler, allowing it to serve as a comment or explanatory note for that particular line of code.

Syntax:

//This is single line comment

CommentExample1.java

public class CommentExample1 {    
public static void main(String[] args) {    
int i=10; // i is a variable with value 10  
System.out.println(i);  //printing the variable i  
}    
}

Output:

10

2) Java Multi-Line Comment

In Java, the multi-line comment is employed to comment out multiple lines of code. It is particularly useful when explaining complex code snippets or when commenting on multiple lines of code simultaneously, as it would be cumbersome to use single-line comments for this purpose.

To create a multi-line comment, the comment section is enclosed between /* and */. Any text appearing between these markers is not executed by the Java compiler, allowing it to serve as a comment or explanation for the specified code section.

Syntax:

/*  
This   
is   
multi line   
comment  
*/

CommentExample2.java

public class CommentExample2 {    
public static void main(String[] args) {    
/* Let's declare and  
 print variable in java. */    
  int i=10;    
    System.out.println(i);    
/* float j = 5.9; 
    float k = 4.4; 
    System.out.println( j + k ); */    
}    
}

Output:

10

3) Java Documentation Comment

Documentation comments are commonly utilized when developing large programs or software applications, as they facilitate the creation of API documentation. This documentation serves as a reference, providing information about the classes, methods, arguments, and other elements used in the code.

To generate the documentation API, the javadoc tool is employed. Documentation comments are enclosed between /** and */. These comments are specifically formatted to capture relevant details about the code, including class descriptions, method explanations, parameter information, and return values.

Syntax:

/**  
* 
*We can use various tags to depict the parameter 
*or heading or author name 
*We can also use HTML tags   
* 
*/

javadoc tags

Tag Syntax Description
{@docRoot} {@docRoot} Represents the relative path to the root directory of the generated document from any page.
@author {@author name – text} Indicates the author of the class.
@code {@code text} Displays the text in code font without interpreting it as HTML markup or nested Javadoc tags.
@version {@version version-text} Specifies the “Version” subheading and includes the version text when the -version option is used.
@since {@since release} Adds a “Since” heading with the specified release text to the generated documentation.
@param {@param parameter-name description} Adds a parameter with the given name and description to the “Parameters” section.
@return {@return description} Required for every method that returns a value (except void), describing the return value.

Let’s use the javadoc tag in a Java program.

Calculate.java

import java.io.*;  
  
/** 
 * <h2> Calculation of numbers </h2> 
 * This program implements an application 
 * to perform operation such as addition of numbers  
 * and print the result  
 * <p> 
 * <b>Note:</b> Comments make the code readable and  
 * easy to understand. 
 *  
 * @author Anurati  
 * @version 16.0 
 * @since 2021-07-06 
 */  
   
 public class Calculate{  
    /** 
     * This method calculates the summation of two integers. 
     * @param input1 This is the first parameter to sum() method 
     * @param input2 This is the second parameter to the sum() method. 
     * @return int This returns the addition of input1 and input2 
     */  
    public int sum(int input1, int input2){  
        return input1 + input2;  
    }  
    /** 
    * This is the main method uses of sum() method. 
    * @param args Unused 
    * @see IOException  
    */    
    public static void main(String[] args) {  
        Calculate obj = new Calculate();  
        int result = obj.sum(40, 20);  
  
        System.out.println("Addition of numbers: " + result);  
    }    
 }

Compile it by javac tool:

Create Document

Create documentation API by javadoc tool:

After the generation process, the HTML files about the Calculate class have been successfully created within the current directory named “abcDemo”. To access the contents, simply open the HTML files in a web browser. Within these files, you will find the detailed explanation of the Calculate class as provided in the documentation comment.

Java comments are executable?

In Java, comments serve as non-executable elements that are ignored by the compiler and interpreter. However, before the lexical transformation of code during compilation, the contents of the code are encoded into ASCII format. This encoding process is performed to facilitate easier processing and handling of the code by the compiler.

Test.java

public class Test{  
    public static void main(String[] args) {  
        //the below comment will be executed  
// \u000d System.out.println("Java comment is executed!!");  
    }  
}

Output:

The above code generates the output because the compiler parses the Unicode character \u000d as a new line before the lexical transformation, and thus the code is transformed as shown below:

Test.java

public class Test{  
    public static void main(String[] args) {  
        //the below comment will be executed  
//  
System.out.println("Java comment is executed!!");  
    }  
}

So, the Unicode character shifts the print statement to the next line and it is executed as a normal Java code.

For further exploration of concepts like Java Comments, we suggest following tutorials.freshersnow.com.