In Java, comments are lines in the code that are ignored by the compiler and interpreter during the program's execution.
Why do we use comments in a code?
- Comments are used to make the program more readable by adding the details of the code.
- It makes easy to maintain the code and to find the errors easily.
- The comments can be used to provide information or explanation about the variable , method, class , or any statement.
- It can also be used to prevent the execution of program code while testing the alternative code.
Types of Java Comments
There are three types of comments in Java.
- Single Line Comment
- Multi Line Comment
- Documentation Comment
1) Java Single Line Comment
A single-line comment is employed to annotate a single line of code. It is a commonly utilized and straightforward method of adding comments to statements.
Comments in Java that are written on a single line begin with two forward slashes (//). Any content preceding // will not be interpreted or executed by the Java compiler.
Syntax
It has the following syntax:
//This is single line comment
Example
The subsequent illustration demonstrates how single-line comments are utilized in Java. Comments that commence with // are disregarded by the compiler. The code outputs the number 10.
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:
2) Java Multi Line Comment
A multi-line comment serves the purpose of commenting on multiple lines of code simultaneously. It is beneficial for providing explanations for intricate code segments or when needing to comment on several lines of code together, which would be cumbersome with single-line comments.
In Java, comments that span multiple lines are enclosed within / and /. The code enclosed within these delimiters is not executed by the Java compiler.
Syntax
It has the following syntax:
/*
This
is
multi line
comment
*/
Example
In Java, multi-line comments are indicated by enclosing comments between / and /. These comments are disregarded by the compiler. In the provided program example, the output is 10, as the compiler skips the commented code.
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:
Note: Usually // is used for short comments and /* */ is used for longer comments.
3) Java Documentation Comment
Documentation comments are commonly utilized in the development of extensive programs for a project or software application to facilitate the generation of API documentation. This documentation is essential for providing a reference to the classes, methods, arguments, and other elements employed in the code.
In order to generate API documentation, the javadoc tool must be utilized. These documentation comments are enclosed within /* and /.
Syntax
It has the following syntax:
/**
*
*We can use various tags to depict the parameter
*or heading or author name
*We can also use HTML tags
*
*/
Example
An illustration below showcases the utilization of a Java documentation comment. It commences with /* and concludes with /, serving the purpose of elucidating the class and its operations.
/**
* This program prints a welcome message.
*/
public class DocCommentExample {
public static void main(String[] args) {
System.out.println("Welcome to Java!");
}
}
Output:
Welcome to Java!
javadoc tags
Here are some of the frequently utilized tags in documentation comments:
| Tag | Syntax | Description |
|---|---|---|
| {@docRoot} | {@docRoot} | to depict relative path to root directory of generated document from any page. |
| @author | @author name - text | To add the author of the class. |
| @code | {@code text} | To show the text in code font without interpreting it as html markup or nested javadoc tag. |
| @version | @version version-text | To specify "Version" subheading and version-text when -version option is used. |
| @since | @since release | To add "Since" heading with since text to generated documentation. |
| @param | @param parameter-name description | To add a parameter with given name and description to 'Parameters' section. |
| @return | @return description | Required for every method that returns something (except void) |
Let's use the Javadoc tag in a Java program.
Example using Javadoc tag
In the demonstration below, Java documentation comments are illustrated in describing a class along with its methods. These comments are initiated with /* / and have the capability to contain tags such as @author, @param, and @return.
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:
The HTML files have been generated for the Calculate class within the existing directory named abcDemo. By opening these HTML files, you will find detailed explanations of the Calculate class as documented in the comments.
Are Java comments executable?
Java comments do not get executed by the compiler or interpreter. Instead, before the code undergoes lexical transformation in the compiler, the code contents are encoded into ASCII to simplify processing.
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 code shown above produces an output due to the compiler interpreting the Unicode character \ u000d as a line break before lexical analysis. Consequently, the code undergoes transformation as illustrated 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!!");
}
}
Therefore, the Unicode character causes the print statement to move to the following line when executed in Java as regular code.