Comments in java

In this post we are going to learn comments in java.

comments in java

Comments in java are description added by the programmer to provide information or explanation within java program.

Comments are not executed by compiler and interpreter.


Types of java comments

There are three types of comments in java they are,

  1. Single line comments
  2. Multi line comments
  3. Documentation

Single line comments

Single line comment start with double slash and it is used to comment only single line.

Syntax:

// single line comment
public class SingleLineComment
{
   public static void main(String[] args) 
   {
      int a = 5; // single line comment example 
      System.out.println(a);
   }
}

Output:

5


Multi line comments

If you have multiple lines to describe code you can use multiline comment. Multi line comment starts with forward slash star ( / * ) and ends with star forward slash ( */ ).

It will comment out everything in between. Compiler will not read this code it will completely ignore.

Syntax:

/* 
This is 
an example for
multi line 
java comment 
*/

public class MultilineComment 
{
   public static void main(String[] args) 
   {
      /* Here we are declaring and 
      printing integer variable b. */
      int b = 5; 
      System.out.println(b);
   }
}

Output:

5


Documentation Comments

Javadoc tool is used to generate documentation comments in HTML format from java source code. This tool comes with JDK.

Documentation comments look very similar to multiline comments but there is a difference. If you look at the beginning, instead of just having one star or asterisk it has two asterisks.

Also read – operators in java

That’s the subtle difference between the two. Basically documentation comment is used to comment multiple lines of code but it also serves the specific purpose of writing documentation.

Syntax:

/** 
* <h1>Area of Square</h1>
* Area of Square java program calculates area 
* using given side value and prints the area.
* <p>
* <b>Note: Adding comments in a java program makes it more
* user friendly and is presumed as good quality code
* 
* @author Sachin
* @version 1.0
* @since 2015-04-12
* </b>
* </p>
*/
public class DocumentationComment 
{
   public static void main(String[] args) 
   {
      double side = 5;      
      double area = side * side; 
      System.out.println("Area of square is : " + area);
   }
}

Output:

Area of Square is : 25.0

In documentation comments we can use tags as well to specify parameter or method. Here are some available tags,

SyntaxTagDescription
@return description@returnadds a “Returns” section with the description text.
@exception class-name description@exceptionadds a Throws subheading to the generated documentation, with the classname and description text.
@author name-text@authoradds the author of a class.
{@docRoot}{@docRoot}represents the relative path to the generated document root directory from any generated page.
{@code text}{@code}displays text in code font without interpreting the text as HTML markup or nested javadoc tags.
@deprecated deprecatedtext@deprecatedadds a comment indicating that this API should no longer be used.
Inherits a comment from the immediate surperclass{@inheritDoc}inherits a comment from the nearest inheritable class or implementable interface.
@param parameter-name description@paramadds a parameter with the specified parameter-name followed by the specified description to the “Parameters” section.
{@linkplain package.class#member label}{@linkplain}identical to {@link}, except the link’s label is displayed in plain text than code font.
{@link package.class#member label}{@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.
@version version-text@versionadds a “Version” subheading with the specified version-text to the generated docs when the -version option is used.
{@value package.class#field}{@value}when {@value} is used in the doc comment of a static field, it displays the value of that constant.
@throws class-name description@throwsthe @throws and @exception tags are synonyms.
@since release@sinceadds a “Since” heading with the specified since-text to the generated documentation.
@serialField field-name field-type field-description@serialFielddocuments an ObjectStreamField component.
@serialData data-description@serialDatadocuments the data written by the writeObject( ) or writeExternal( ) methods.
@serial field-description | include | exclude@serialused in the doc comment for a default serializable field.
@see reference@seeadds a “See Also” heading with a link or text entry that points to reference.