Comments in Java

Overview

In this article, I will tell you all about comments in Java. Every programming language has a predefined comment structure. In Java, there are 3 types of comments.

1. Single line comment
2. Multi-line comment
3. Documentation comment

Before knowing about these, first, let us see why a programming language needs comments!

Why Comments?

Comments are pieces of text notes that are added to a program in order to describe something about the program or provide any information.

• Comments make the programs more human readable and easier to understand.
• Any statement written as comments is non-executable.
• The compiler and interpreter ignore these statements while compiling the program.
• These do not affect the flow of the program or the output.

Uses of Comments

1. Code Description:
   

   – Programmers give comments to describe a particular piece of code or a particular logic to help others understand.
   – Comments are also used to describe an algorithm of a method or a short summary of the code.

2. Information about the Source Code:

   – Comments contain information about the author of the initial version of the program, date of creation, compatible environments on which the code can run, IDE information, people who have modified the program so far.
   – Copyright notices can be written as comments inside the source code. This information helps in maintenance.

3. Planning and Debugging:

   – Comments can contain initial planning steps like small algorithms, pseudo codes. These help the programmer later while developing the whole program.
   – It can be used to mark specific locations in the existing source code where the programmer intends to modify something or insert something later.
   – For debugging, we generally insert many print statements to identify errors. After debugging we can comment off these statements.
   – Sometimes, we want to see the functionality without some specific lines of code. In that case, instead of deleting those lines, we can simply comment on them.

4. Automatic documentation generation:
   

   – Many programming tools provide a facility for generating API documentation from the comments present in the source program. These may contain information about versioning, any syntax highlights or any header information. This process makes the documentation process and maintenance of the code easy.

To sum up, we can say that comments make our tasks easier.

Types of Comments in Java:

1. Single line Comment:
   

   This is used to comment on a single line in a program. The syntax is as follows:
   // This represents a single line Comment

2. Multi-line Comment:
   

   To comment on multiple lines in a program, we use this type of comment. The syntax is as follows:

   /* This is multi-line comment statement 1
   * This is multi-line comment statement 2
   */

3. Documentation Comment:
   We place these doc comments above the methods or classes which we want to document. The JDK Javadoc tool uses these doc comments to automatically prepare documentation of the source code. This comment is very much similar to multi-line comment except for an extra “*”.

   This supports different tags like @author, @link, etc.
   

   /** This represents documentation comments.
   * This is Javadoc
   * 
   * @author Ipsita
   */

Refer to the program below for a clear understanding of the comments. The program displays all the 3 types of comments available in Java.

public class JavaComments {

  public static void main() {
    
    // This represents a single line Comment
    
    System.out.println("single line comment");
    //System.out.println("SINGLE LINE COMMENT");
    
    
    /* This is multi line comment statement 1
     * This is multi line comment statement 2
     */		
    System.out.println("multi line comments");
    
    /* System.out.println("MULTI LINE COMMENT STATEMENT 1");
    System.out.println("MULTI LINE COMMENT STATEMENT 2");
    We have commented the above 2 statements, so it will not get executed.
    */
    
    /** This represents documentation comments.
     * This is Javadoc
     *  @author Ipsita
     */
    System.out.println("Documentation type comments");
    
    /** System.out.println("DOCUMENTATION TYPE COMMENTS");
     */
  }
}

Now that we know how to add comments, we can improve the readability of our programs. In the next article, you will learn the types of variables in java and everything about them.