In a program, comments are like indents one makes, they are used so that it is easier for someone who isn’t familiar with the language to be able to understand the code. It will also make the job easier for you, as a coder, to find errors in the code since you will be easily able to find the location of the bug. Comments are ignored by the compiler while compiling a code, which makes the job more complex in the long run when they have to go through so much code to find one line.
In Java there are three types of comments:
- Single-line comments.
- Multi-line comments.
- Documentation comments.
A. Single-line comments
A beginner-level programmer uses mostly single-line comments for describing the code functionality. It’s the easiest typed comments.
Syntax:
//Comments here( Text in this line only is considered as comment )
Illustration:
Examples in an actual code
Example:
Java
// Java program to show single line comments class Scomment{ public static void main(String args[]) { // Single line comment here System.out.println("Single line comment above"); }} |
Output:
Single line comment above
B. Multi-line Comments:
To describe a full method in a code or a complex snippet single line comments can be tedious to write since we have to give ‘//’ at every line. So to overcome this multi-line comments can be used.
Syntax:
/*Comment starts continues continues . . . Comment ends*/
Example:
Java
//Java program to show multi line commentsclass Scomment{ public static void main(String args[]) { System.out.println("Multi line comments below"); /*Comment line 1 Comment line 2 Comment line 3*/ }} |
Output:
Multi line comments below
We can also accomplish single line comments by using the above syntax as shown below:
/*Comment line 1*/
C. Documentation Comments:
This type of comment is used generally when writing code for a project/software package, since it helps to generate a documentation page for reference, which can be used for getting information about methods present, its parameters, etc. For example, http://docs.oracle.com/javase/7/docs/api/java/util/Scanner.html is an auto-generated documentation page that is generated by using documentation comments and a javadoc tool for processing the comments.
Syntax:
/**Comment start * *tags are used in order to specify a parameter *or method or heading *HTML tags can also be used *such as <h1> * *comment ends*/
Java
/*package whatever //do not write package name here */ import java.io.*; class GFG { public static void main (String[] args) { /** comment line 1 comment line 2 */ }} |
Available tags to use:
| Tag | Description | Syntax |
|---|---|---|
| @author | Adds 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} | Represents the relative path to the generated document’s root directory from any generated page. | {@docRoot} |
| @deprecated | Adds a comment indicating that this API should no longer be used. | @deprecated deprecatedtext |
| @exception | Adds a Throws subheading to the generated documentation, with the classname and description text. | @exception class-name description |
| {@inheritDoc} | Inherits a comment from the nearest inheritable class or implementable interface. | Inherits a comment from the immediate surperclass. |
| {@link} | Inserts an in-line link with the visible text label that points 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 | Adds a parameter with the specified parameter-name followed by the specified description to the “Parameters” section. | @param parameter-name description |
| @return | Adds a “Returns” section with the description text. | @return description |
| @see | Adds a “See Also” heading with a link or text entry that points to 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 | Adds a “Since” heading with the specified since-text 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 | Adds a “Version” subheading with the specified version-text to the generated docs when the -version option is used. | @version version-text |
Implementation:
Java
// Java program to illustrate frequently used // Comment tags /*** <h1>Find average of three numbers!</h1>* The FindAvg program implements an application that* simply calculates average of three integers and Prints* the output on the screen.** @author Pratik Agarwal* @version 1.0* @since 2017-02-18*/public class FindAvg { /** * This method is used to find average of three integers. * @param numA This is the first parameter to findAvg method * @param numB This is the second parameter to findAvg method * @param numC This is the second parameter to findAvg method * @return int This returns average of numA, numB and numC. */ public int findAvg(int numA, int numB, int numC) { return (numA + numB + numC)/3; } /** * This is the main method which makes use of findAvg method. * @param args Unused. * @return Nothing. */ public static void main(String args[]) { FindAvg obj = new FindAvg(); int avg = obj.findAvg(10, 20, 30); System.out.println("Average of 10, 20 and 30 is :" + avg); }} |
Output:
Average of 10, 20 and 30 is :20
For the above code documentation can be generated by using the tool ‘javadoc’:
Javadoc can be used by running the following command in the terminal.
javadoc FindAvg.java
This article is contributed by Pratik Agarwal. If you like Lazyroar and would like to contribute, you can also write an article using write.geeksforgeeks.org or mail your article to review-team@geeksforgeeks.org. See your article appearing on the Lazyroar main page and help other Geeks.
Please write comments if you find anything incorrect, or if you want to share more information about the topic discussed above.
