Introduction

Every good programmer you ever talk to stresses equally on code readability as much as having the ability to understand logic behind code. This is only because your source code is of no value if other developers cannot understand what you have written down thereby taking away the opportunity to expand and improve on your work later. Other than following good programming conventions and adhering to a specific framework best suited for the project you are working on, commenting your code goes a long way to improve the readability quotient of your program.

Comments in Java

Comments are lines of text enclosed within or starting with special characters (discussed below) normally laying out a brief description of what a particular chunk of your code executes or performs. These statements are not executed either by the interpreter or the compiler. Comments generally give information or explanation about classes, methods, variables, or any statement in your program in general. The convention that most programmers follow is adding comments before that part of the code. When reading the code, a developer first reads the description of the code followed by the actual source code. Comments are also used to hide parts of your program. This is commonly known as ‘commenting out’ segments of the code.

Types of Java Comments

• Single-Line Comments – As the name suggests, a single-line comment is used to comment only one line in Java programs.
• Multi-Line Comments – Multi-line comments are used to add comments ranging several lines.
• Documentation Comments – Just like in other coding languages, documentation comments in Java is also used to create the documentation API. The javadoc tools needs to be used to create documentation API.

Let us understand each of these types of comments in detail.

Single Line Comments

As the name suggests, these comments usually span a single line of you Java editor and are normally used by beginner level programmers to document certain functionalities of their code. The syntax of single line comments is as follows:

All single line comments start with ‘//’ and no closing characters are required. When you type ‘//’ at the start of a particular line, that line is already commented out and the compiler will ignore it at run-time. You can put in as many single line comments as you want, either spaced out throughout the code or consecutively.

Example:

//The following is a demo Java program to print out ‘Hello World’.
//More comments (Compiler will not execute comments.)
class HelloWorld{
//Main method
public static void main { …..
…
} }

Multi line Comments

When you need to write long comments that describe an entire method or complex parts of your code, it is always not feasible to fit everything in one line. It also becomes a logistical problem if you have to use ‘//’ before the start of every comment line. In such cases, Java gives you the option of making multi line comments. The syntax is as follows:

/* This is an illustration of multi line comment within Java Programs
The following is a sample Java code that prints out
Hello World.
Add some more comments here */
class HelloWorld
{
public static void main (String args [])
{
/*
Add some comments here
Line1
Line2
Line3
*/
System.out.println (“Hello World”);
}
}

Documentation Comments

When you are coding for a big project/software package, it is required that you extensively comment every step of the way. In such cases, the documentation commenting style is used such that a documentation page can later be generated as a reference to your work.

Syntax:

/**
*Comments
*Line1
*Line2
*Line3
*Line4
*Line4
*/
class HelloWorld
{
public static void main (String args [])
{
….
}
}