Introduction to Java comments
Documenting our code is very important as it helps others to understand it, and even to remind ourselves how our code works. Unfortunately, it is easy for most external documentation to become out of date as the program changes and we update the program. That is why it is useful to write documentation as comments inside the program itself where it is easy to update and change the comment along with the program. Moreover,  Javadoc is a documentation tool that defines a standard format for such comments, and which can generate HTML files to view the documentation from a web browser.
In this tutorial, we will cover all the concepts of java comments including single and multiline comments through various examples. In a nutshell, this tutorial covers all the information that you need to learn in order to start documenting your java program.
What are Java comments?
The Java comments are the statements in a program that are not executed by the compiler and interpreter. While executing the program the compiler or the interpreter ignores the java comments. It is well said that comments are not for machines, they are for humans. We add comments in our program to make it understandable for others who read our program.
These are the following advantages of adding comments to our program.
- Comments are used to make the program more readable by adding the details of the code.
- Comments make it easy to maintain the code and to find the errors easily.
- The comments can be used to provide information or explanation about the variables method, class, or any statement.
In the following section, we will take real examples of java comments and see how they can be useful.
Java single line comments
Single line comments are useful when we need to define variables instantly or give a very short intro of the following code. There is no any specific place for comments but it is recommended to add comments in the same indentation level of the code. In this section, we will see the syntax of java single-line comments and take some examples.
Syntax and examples of java single line comments
Now let us see how we can add comments to our java program. In java, single-line comments are represented or add after double forward slashes (//
). See the following syntax of java single-line comment.
// this is single line java comment
Anything that we write after the after double forward slashes will be ignored by the java compiler. Now let us see take a real example of java single-line comments. See the example below:
public class Main {
   public static void main(String[] args) {
       // java program to print the name
       System.out.println("This is java tutorial");
  }
}
Output:
This is java tutorial
Notice that neither we get an error, not the statement after the double slash has been print because the java interpreter ignores all the statements written after double forward slashes. Usually, the comments are used to explain complex ideas, formulae, and algorithms. For example, see the example below which explains the code.
// This formula finds the percentage
 per = (obtain_Marks /total_marks)*100
It is important and a best practice is to write comments in the same intended level of code.
See the following example which shows the programmatic way of writing single-line java comments.
public class Main {
   public static void main(String[] args) {
       // First for loop ( outer most)
       for(int i = 0; i < 5; i++){
           // second for loop
           for (int k = 0; k <10; k+=2){
               // inner most loop
               for (int l = k; l<20; l++){
                   // printing the welcome
                   System.out.println("Welcome to java tutorial");
              }
          }
      }
  }
}
This is the best practice of writing single-line java comments and it looks good as well.
Java inline comments
It is not necessary to write the single-line java comments above the line, java also supports inline comments as well. That means we can add comments and code in the same line and the interpreter will only execute the code and will ignore the comment. Now it is important to add inline comments after the code, otherwise, the code itself will also be included in the java comment.
See the following simple syntax of the java inline comment.
data = 10 // defining variable
Here the interpreter will only read the code/text that is before the double slashes and anything after the double slashes will be considered to be a comment. Now, this method is very useful and saves our lines and makes our code clear and clean. Unlike block comments which take one whole line.
See the example below which uses java inline comments.
public class Main {
   public static void main(String[] args) {
       for(int i = 0; i < 5; i++){ // outer for loop
           for (int k = 0; k <10; k+=2){ // second for loop
               for (int l = k; l<20; l++){ // inner most for loop
                   System.out.println("Welcome to java tutorial"); //prints welcome
              }
          }
      }
  }
}
Notice that this time our code takes fewer lines because we had used inline comments instead of using single-line java comments.
Java multiline comments
So far we had learned how we can write a single line and inline comment to explain our code. In this section, we will see how we can write multiline comments in a java programming language. Because sometimes single-line java comments cannot explain the whole process and the formulae. So in such cases, we need to write java multiline comments in more than one line.
Unlike python programming language, Java supports multi-line commenting and in this section, we will see how we can add multiline comments in java.
Syntax and examples of java multiline comments
In java programming language we need to start our multiline comments with forward-slash and an asterisk symbol and end the comment with double asterisk symbols followed by a forward slash. Here is the simple syntax of java multiline comments.
/* this is the starting of java multiline comments
comments inside multiline comments
ending of java multiline comments **/
Now let us take a real example and see how we can write multiline comments in a java programming language.
public class Main {
   /* Author: Bashir
  Date : 26.08.2021
   about: Computer sciece student**/
 }
Notice that we add a double asterisk with a forward slash at the end of the comment and it is very important to add because it tells the interpreter that the multiline comment ends here. If we will not add it, the whole program even the code will be included inside the comment.
Here is another example of java multiline comments which explains the purpose of the newly created class. See the example below:
public class Main {
   /* This is java class
  It contains all the details about university
  It may the statistic values as well
  **/
}
An alternative way to write multiline comments in java
We know that java supports multiline comments through a special syntax. However, there is an alternative to write the java multiline comments. Simply we can write single-line comments consecutively to make and look like multiline comments. See the example below:
public class Main {
   // Author : Bashir
   // Date : 26.08.2021
   // about: Computer science student
}
Notice that we have to use consecutive single-line comments to make it look like a multiline comment. The benefit of using this strategy is that we don't need to be worried about the ending part but the disadvantage is that we have to put double slashes at the starting of each new line.
Introduction to Javadoc comments
Documentations of comments are usually used to write large programs for a project or software application as it helps to create documentation API. These APIs are needed for reference, i.e., which classes, methods, arguments, etc., are used in the code. In java, there is a special tool known as the Javadoc tool which helps us to create documentations. In this section, we will learn how we can create documentation using the Javadoc tool
Syntax and examples of Javadoc
In general, Javadoc comments are similar to multi-line comments that are placed before class, field, or method declarations. They must begin with a slash and two stars, and they can include special tags to describe characteristics like method parameters or return values. The HTML files generated by Javadoc will describe each field and method of a class, using the Javadoc comments in the source code itself. Here is the simple syntax of Javadoc.
public class Main {
  /**
  * Author: BashirÂ
  * Date : 26.08.2021 Â
  * About: Computer science student
   */  Â
}
Javadoc also has some Tags that can be used at the end of each Javadoc comment to provide more structured information about the code being described. For example, most Javadoc comments for methods include "@param
" and "@return
" tags when applicable, to describe the method's parameters and return value. The "@param
" tag should be followed by the parameter's name, and then a description of that parameter. The "@return
" tag is followed simply by a description of the return value. Here is a list of some of those tags.
{@docRoot}
: it is used to depict relative path to the root directory of generated document from any page@author
: it is used to add the author of the class.@code
:Â it is used to show the text in code font without interpreting it as html markup or nested javadoc tag.@version
: it is used to specify "Version" subheading and version-text when -version option is used.@return
: Required for every method that returns something (except void)
Now let see an example that uses these tags.
public class Main {
  /**
 * Return the name of university.
  * @return this is the name of univeristy.
  */
 public String getName() {
   return name;
 }
/**
 * Changes name.
 * Takes some time
  * @param newName This is new name of university
  */
 public void setName(String newName) {
   name = newName;
}
}
Use keyboard shortcuts for Java multiline comments
Sometimes, it might be boring to add multiline one by one ( single consecutive ones) or to add the starting and ending part of multiline comments (/**......*/)
. However, visual studio code provides us some simple and shortcut ways to add comments to the java without manually typing the starting and ending.
To add a single line java comment, just write the comment and then press Ctrl + forward-slash (ctrl + /
) and the statement will be converted into a java comment. It is the easiest and short way to add comments.
If we want to add multiline comments without manually typing the starting and ending parts, we can do that as well. To add multiline comments consisting of consecutive single line comments, just select the are and again press ctrl + /
and the highlighted section will be converted to multiline comments as shown in the picture below:
After selecting the area/blocks of code, we have to press CTRL + /
(Forward slash) and the whole selected area will be converted into comments as shown below:
Now, if we wanted to add multiline comments, not the consecutive single-line ones, we can do that as well. First of all, we have to select the area and then enter Ctrl + shift + A
and the whole selected area should be converted to java multiline comments as shown in the picture below:
Now press Ctrl + shift + A
and the selected area should be converted to multiline comments as shown below:
Moreover, there are many extensions available for visual studio code, which auto-generates comments, you can download and install any of them and generate auto comments as well.
Summary
In any programming language, comments are really important as they help others to go through your code and understand each step easily. Moreover, comments are like documentation that describes each part of the program. In this tutorial, we learned about java single and multiline comments. We covered different types of comments that we supported by java programs like a single line, multiline and Javadoc.
We learned the syntax of each of these methods by taking various different examples. Moreover, we also cover some of the Javadoc tags as well. All in all, this is a full tutorial about java comments which gives you an in-depth understanding of comments.
Further Reading
Java comments documentation
Java multiline comments
Javadoc documentataionÂ
nice