In this post, we will learn about different type of comments available in Java.
Like most other programming languages, Java lets you enter a remark into a program's source file. The contents of a comment are ignored by the compiler. Instead, a comment describes or explains the operation of the program to anyone who is reading its source code.
Java supports three styles of comments
- Single-line comment
- Multiline comment
- Documentation comment
1. single-line comment
A single-line comment begins with a // and ends at the end of the line.
Syntax:
// Your program begins with a call to main().
Example:
// demonstrate single line comment
public class SingleLineComment {
public static void main(String[] args) {
// single line comment can be put here
System.out.println("Single line comment example");
}
}
Output:
Single line comment example
2. Multiline comment
This type of comment must begin with /* and end with */. Anything between these two comment symbols is ignored by the compiler. As the name suggests, a multiline comment may be several lines long.
Syntax:
/*
This is a multiline comment example.
You can comment multiple lines of code or write about what program is doing.
*/
Example:
/*Demonstrate multi line comment example
javac MultiLineComment.java
java MultiLineComment
*/
public class MultiLineComment {
public static void main(String[] args) {
System.out.println("Multi line comment example");
/*
comment line 1
comment line 2
comment line 3
..............
..............
*/
}
}
Output:
Multi line comment example
3. Documentation comment
This type of comment is used to produce an HTML file that documents your program. The documentation comment begins with a /** and ends with a */.
Documentation comments allow you to embed information about your program into the program itself. You can then use the javadoc utility program (supplied with the JDK) to extract the information and put it into an HTML file. Documentation comments make it convenient to document your programs.
Syntax:
/** Comment start
*
* Document tag begin with (@) is called stand-alone tag
* tag begin with {@code} is called in-line tag
* You can also use standard HTML tags in a documentation comment
*
*comment ends */
Example:
// program to demonstrate documentation comment
/**
*
*
* <h1>Find factorial of number</h1>
*
* This program find the factorial of given number
*
* @author santosh
*/
public class DocumentationComment {
/**
* Method to find the factorial of a number
*
* @param n This is first parameter to fact method
* @throws Exception
* @return fact this will return int value
*/
static int fact(int n) throws Exception {
if (n < 0) throw new Exception("Factorial of negative number is always infinity");
if (n == 0 || n == 1) return 1;
int fact = 1;
for (int i = 1; i <= n; i++) {
fact = fact * i;
}
return fact;
}
/**
* @param args
* @throws Exception
*/
public static void main(String[] args) throws Exception {
for (int i = 0; i <= 5; i++) {
System.out.println("Factorial of " + i + " is : " + fact(i));
}
}
}
Output:
Factorial of 0 is : 1 Factorial of 1 is : 1 Factorial of 2 is : 2 Factorial of 3 is : 6 Factorial of 4 is : 24 Factorial of 5 is : 120
Let's know more about factorial in more details.
Table of Javadoc Tags
| Tag | Description | Syntax |
|---|---|---|
| @author | Identifies the author. | @author description |
| {@code} | It displays text in code font without interpreting the text as HTML markup or nested javadoc tags. | {@code code-snippet} |
| @deprecated | This tag specify that a program element is deprecated. | @deprecated description |
| {@docRoot} | Specifies the path to the root directory of the current documentation. | {@docRoot} |
| @exception | Tag describes an exception to a method. | @exception exception-name explanation |
| {@inheritDoc} | This tag inherits a comment from the immediate superclass. | {@inheritDoc} |
| {@link} | Tag provides an in-line link to additional information. | {@link pkg.class#member text} |
| {@linkplain} | Inserts an in-line link to another topic. The link is displayed in plain-text font. | {@linkplain} |
| {@literal} | The {@literal} tag enables you to embed text into a comment. That text is then displayed as-is, without any further processing, such as HTML rendering. | {@literal description} |
| @param | The @param tag documents a parameter. | @param parameter-name explanation |
| @return | The @return tag describes the return value of a method. | @return explanation |
| @see | The @see tag provides a reference to additional information. | @see reference |
| @serial | The @serial tag defines the comment for a default serializable field. | @serial description |
| @serialData | The @serialData tag documents the data written by the writeObject( ) and writeExternal( ) methods. | @serialData description |
| @serialField | Used to document an ObjectStreamField component. | @serialField name type description |
| @since | The @since tag states that an element was introduced in a specific release. | @since release |
| @throws | The @throws tag has the same meaning as the @exception tag. | @throws class-name description |
| {@value} | The first form display the value of constant, which must be a static field. The second form displays the value of a specified static field. | {@value} {@value pkg.class#field} |
| @version | The @version tag specifies the version of a class or interface. | @version info |
This is another example of documentation comments. Each comment immediately precedes the item that it describes. After processed by javadoc, the documentation of the SquareNumber class will be found in SquareNumber.html.
javadoc SquareNumber.java
Example:
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
/**
* This class demonstrates documentation comments.
*
* @author Santosh
* @version 1.2
*/
public class SquareNumber {
/**
* This method returns the square of num. This is a multiline description. You can use as many
* lines as you like.
*
* @param num The value to be squared.
* @return num squared.
*/
public double square(double num) {
return num * num;
}
/**
* This method inputs a number from the user.
*
* @return The value input as a double.
* @exception IOException On input error.
* @see IOException
*/
public double getNumber() throws IOException {
// create a BufferedReader using System.in
InputStreamReader isr = new InputStreamReader(System.in);
BufferedReader inData = new BufferedReader(isr);
String str;
str = inData.readLine();
return (new Double(str)).doubleValue();
}
/**
* This method demonstrates square().
*
* @param args Unused.
* @exception IOException On input error.
* @see IOException
*/
public static void main(String args[]) throws IOException {
SquareNumber ob = new SquareNumber();
double val;
System.out.println("Enter value to be squared: ");
val = ob.getNumber();
val = ob.square(val);
System.out.println("Squared value is " + val);
}
}
Output:
Enter value to be squared: 3 Squared value is 9.0
As a general rule, programmers use multiline comments for longer remarks and single-line comments for brief, line-by-line descriptions.
No comments :
Post a Comment