Java comments

In this article you will learn a lot about Java comments. First we will look at what is a comment, why comments are needed, what are the different types of comments and finally some example programs which will show you how to use comments in Java programs.

 

Introduction

 

Writing comments is considered a good programming practice. They will help the client programmers to understand the programs developed by you.

 

Java comments can be a single line or multiple lines of text which are written by the programmers for documentation purpose. A programmer can write comments to mention the purpose of the program or a part of the program or to provide authorship details.

 

Need for comments

 

Following are some of the famous reasons for writing comments in programs:

• Provide the purpose of the program along with sample input and output of the program.
• Provide authorship details.
• Mention date and time of creation of the program and when it was last modified.
• Provide details about several parts of the program.
• For generating documentation which will be helpful for other programmers.

 

Types of comments

 

In  Java, there are three types of comments. They are:

• Single line comments
• Multi-line comments
• javadoc comments

 

A single line comment as the name implies is a comment containing a single line of text. A single line comment starts with //. All the characters after the // to the end of the line is treated as a comment. Syntax for single line comment is as shown below:

 

// This is a single line comment

 

To write a comment containing more than one line, we can use a multi-line comment. A multi-line comment starts with /* and ends with */. Syntax for writing a multi-line comment is as shown below:

 

/*  This is a
multi-line
comment */

 

We can use a multi-line comment for writing a single line comment as shown below:

 

/* This is a single line comment. */

 

Both single line comments and multi-line comments can be written anywhere in the program.

 

The third type of comments called javadoc comments can be used to generate HTML documentation which can be viewed using a browser. This can help the client programmers to understand the classes that you create. A javadoc comment starts with /** and ends with */. Syntax for writing a javadoc comment is as shown below:

 

/**
* This is a
* javadoc comment
*/

 

Note that * is not necessary before each line of text. It is widely accepted usage of javadoc comments by Java developers. Generally javadoc comments are written at the top of the program. Comments which are written before a class declaration are known as header comments.

 

We can mention several types of specific information like author name, parameters of a function, return value of a method and many more using a javadoc comment. For complete information regarding the javadoc comment and its usage refer this link.

 

Example program using all the three types of comments:

/**
* Purpose: To demonstrate a Java class and object
* Author: Suryateja
* Email: xyz@gmail.com
* Creation Date: 25/9/2014
* [javadoc comment]
*/ 
class Boy
{
	//Field used to store the name of a boy
	String name;
	//Field used to store the address of a boy
	String address;
	//Field used to store the age of a boy
	int age;
	void tellName(){ };
	void tellAddress(){ };
	void tellAge(){ };
	/*
		main method is the entry point of every Java program.
		Here an object for the Boy class is created and values are
		assigned to the fields name, address and age
		[multi-line comment]
	*/
	public static void main(String[] args)
	{
		Boy obj = new Boy();
		obj.name = "George";
		obj.address = "Los Angels, USA";
		obj.age = 23;
		//Print the value of name field
		System.out.println("Name of the boy is: "+obj.name);
		//Print the value of address field
		System.out.println("Address of the boy is: "+obj.address);
		//Print the value of age field
		System.out.println("Age of the boy is: "+obj.age);
		//This is a single line comment
	}
}

 

One thing to remember about comments is, they cannot be nested. For example, the following is a incorrect way of writing comments:

 

//This is a //bad single line comment

 

Every comment started using a beginning marker must be closed with a ending marker. Following is an example of wrong way of writing comments:

 

/*
This is
a bad
multi-line
comment /

 

Note that in the above example, the ending marker should be */.