In this tutorial you will learn about the Java Comments and its application with practical example.
Java Comments
Comments are a set of statements that are not executed by the compiler. The use of comments makes it easy for humans to understand the source code. Usually, comments give you an inside or explanation about the variable, method, class, or any statement that exists in the source code. The comment statements are ignored during the execution of the program.
Types of Java Comments
In Java, there are 3 types of comments.
- Java Single Line Comment
- Java Multi Line Comment
- Java Documentation Comment
Java Single-line Comments
A ‘//’ (double forward slash) is used to specify a single line comment, which extends up to the newline character. This can be used to comments-out everything until a line break
Syntax:-
|
1 |
//This is single line comment |
Example:-
|
1 2 3 4 5 6 7 8 |
public class Main { public static void main(String[] args) { System.out.println("Hello World!"); // It prints Hello, World! } } |
Output:-
|
1 |
Hello World! |
Java Multi-line Comments
If you want to comment on multiple lines then you can do it using /* and */, everything in between from /* to */ is ignored by the compiler-
Uses:-
- Useful for commenting out a section of code
- Cannot be nested within other multi-line comments
Syntax:-
|
1 2 3 4 5 6 |
/* This is multi line comment */ |
Example:-
|
1 2 3 4 5 6 7 8 9 10 11 12 |
public class Main { public static void main(String[] args) { /* It prints Hello World! */ System.out.println("Hello World!"); } } |
Output:-
|
1 |
Hello World! |
Java Documentation Comment
This is a special type of comment mainly used to generate documentation or reference for a project/software package. This can also be used to create documentation API. To create documentation API, we have to use the Javadoc tool.
Uses:-
- Similar to multi-line comments but used to document Java code (classes, methods, fields)
- Extracted using Javadoc command-line utility
Available Tags:-
| Tag | Description | Syntax |
|---|---|---|
| @author | Used to specify the author of a class. | @author name-text |
| {@code} | Displays text in code font without interpreting the text as HTML markup or nested javadoc tags. | {@code text} |
| {@docRoot} | Used for a relative path to the generated document’s root directory from any generated page. | {@docRoot} |
| @deprecated | Used to add a comment indicating that this API should no longer be used. | @deprecated deprecated text |
| @exception | Adds a Throws subheading to the generated documentation, with the class name and description text. | @exception class-name description |
| {@inheritDoc} | It inherits a comment from the nearest inheritable class or implementable interface. | Inherits a comment from the immediate superclass. |
| {@link} | It is used to insert an in-line link with the visible text label which links to the documentation for the specified package, class, or member name of a referenced class. | {@link package.class#member label} |
| {@linkplain} | Identical to {@link}, except the link’s label is displayed in plain text than code font. | {@linkplain package.class#member label} |
| @param | Used to specify a parameter with the specified parameter name followed by the description. | @param parameter-name description |
| @return | Specify a “Returns” section with the description text. | @return description |
| @see | Specify a “See Also” heading with a link or text entry that points to a reference. | @see reference |
| @serial | Used in the doc comment for a default serializable field. | @serial field-description | include | exclude |
| @serialData | Documents the data written by the writeObject( ) or writeExternal( ) methods. | @serialData data-description |
| @serialField | Documents an ObjectStreamField component. | @serialField field-name field-type field-description |
| @since | Used to specify a “Since” heading to the generated documentation. | @since release |
| @throws | The @throws and @exception tags are synonyms. | @throws class-name description |
| {@value} | When {@value} is used in the doc comment of a static field, it displays the value of that constant. | {@value package.class#field} |
| @version | Used to specify a version | @version version-text |
Syntax:-
|
1 2 3 4 5 6 |
/** This is documentation comment */ |
Example:-
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
/** * <h1>Find sum of two numbers!</h1> * The FindSum program implements an application that * simply calculates sum of two integers and Prints * the output on the screen. * * @author W3Adda * @version 1.0 * @since 2018-04-13 */ public class FindSum { /** * This method is used to find sum of two integers. * @param numA This is the first parameter to findSum method * @param numB This is the second parameter to findSum method * @return int This returns sum of numA and numB. */ public int findSum(int numA, int numB) { return (numA + numB); } /** * This is the main method which makes use of findSum method. * @param args Unused. * @return Nothing. */ public static void main(String args[]) { FindSum obj1 = new FindSum(); int result = obj1.findSum(10, 20); System.out.println("Sum of 10 and 20 is :" + result); } } |
Output:-
|
1 |
Sum of 10 and 20 is :30 |
For the above program, documentation can be generated by using the tool ‘Javadoc’ as follows –
|
1 |
javadoc FindSum.java |
