Comments in java

Let’s learn comments in java.

Comments in java

Comments are description added by programmer to provide information about a method, class or variable.

Java comments are not executed or ignored by compiler.


There are 3 types of comments in java.

comments in java
  1. Single line comment (// comments)
  2. Multi line comment (/* comments */)
  3. Documentation comment (/** documentation */)

Single line comment

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

Example:

// integer variable 'a' is assigned value 5
int a = 5;


Multi line comments java

Multiline comment starts with forward slash star ( /* ) and ends with star forward slash ( */ ).

Multiline comment will comment out everything in between /* and */. Java compiler will completely ignore.

Syntax:

/*
This is
an example for
java multiline comment
*/


Example:
/* Here we are declaring and
printing integer variable b. */
int b = 5;
System.out.println(b);



Documentation comments

Java documentation comment is mainly used to create documentation Application Programming Interface(API).

Also read – operators in java

Javadoc is a tool in java comes with JDK and used for generating java code documentation in HTML format from java source code.

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>
*/

Example:
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

Compile above java program: javac Documentation.java

create documentation API by javadoc tool: javadoc Documentation.java


javadoc tags – comments in java

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.

comment in java shortcut

Shortcut to comment code in eclipse is as follows,

  • CTRL + / –> to comment single line of code.
  • CTRL + / –> the same shortcut works to uncomment line of code, which is already commented.
  • CTRL + SHIFT + / –> to comment block of code consisting of 3 or more lines.
  • CTRL + SHIFT + \ –> to uncomment block of code, which is already commented.

java comments best practices

Here are java comments best practices.

  • use single line comments to mention business logic.
  • use multi-line comments to comment unused code.
  • use documentation comments when documentation to be generated.