Comments in Java - Scientech Easy

Comments in Java are statements that describe the features of a program. It allows the programmers to compose and express their thoughts related to the code independently. It is a good habit to write comments related to code in a program.

Java comments are not executed by the compiler and interpreter. During compilation, the Java compiler omits all comments, ensuring that the execution and performance of the program remains unaffected.

We only use the comments to provide information about variables, methods, classes, or any statement in any programming language. For example, here is a comment that explains the value used to initialize a variable “x”:

double x = 50.50; // Variable declaration and initialization.

This comment explains the declaration and initialization of a variable with a value. Comments can also be used to hide program code.

Why should We Write Comments in Java Program?

We should write comments related to the code because comments help programmers who read your code understand your thoughts.

This means that comments increase the readability and understandability of the program. So, if a program is understandable, then it helps others to easily follow our code.

If other members of the application development team do not understand our program, then they may not be able to implement it in the project and will reject your code.

Therefore, writing comments is compulsory in any program to make the code understandable. In addition, we will find comments helpful when we review our own program code.

Types of Comments in Java

There are three types of comments in Java that are as follows:

Single line comment
Multi line comment
Java documentation comment

Let us understand all of them one by one.

Single line Comment:

It is used for making a single line as a comment. Single line comment is also called inline comment that provides brief summary comments for a single line.

It begins with a double slash symbol / / and after this, whatever is written till the end of the line is considered as a comment.

For example:

// Variable declaration for Compound Interest.
   float pincipalAmount, timePeriod, rateOfInterest;

We can also use the trailing comment to provide an explanation for a single line of code. Start trailing comments with a double slash (//) and place it to the right of the line of code it refers to.

For example:

int s = a + b + c; // Adding three numbers and store it into a variable s of type int.

Multi line Comments:

These comments are used for commenting several lines as comments. Multi line comments begin with / * and end with * /. In between / * and * /, whatever will be written, will be treated as a comment by Java and everything will ignore by java compiler until it finds a */.

For example:

/* 
This  
is  
multi line  
comments 
*/

Java Documentation Comments:

These comments begin with / * * and end with * /. Java documentation comments are used to provide explanations for every feature in a Java program.

This explanation proves helpful in the development of a .html file called API (Application Programming Interface) document.

For example:

/**
This
is
documentation
comment
*/

Best Practices for Writing Comments in Java

Writing effective comments in Java or any other programming languages requires adhering to some best practices. They are as:

Keep comments concise, clear, and to the point, ensuring they add value without being verbose.
Use clear and descriptive language to explain complex algorithms, functions, or classes.
You should also update the comments accurately when you update the code.
Avoid Redundant Comments. Only add comments when necessary; avoid reiterating the obvious.

Commenting Conventions and Guidelines

To maintain consistency of writing comments in the code, follow these commenting conventions and guidelines:

Adopt a uniform formatting style for all comments, ensuring they are easy to read and understandable for anyone.
Always place proper comments close to the code they refer to, providing better context.
Always double-check comments for grammatical errors and spelling mistakes to maintain expertise.