Using Java Comments

All Programming Languages Support Comments Which are Ignored by the Compiler

Krzysztof Zmij/E+/Getty Images

Java comments are notes in a Java code file that are ignored by the compiler and runtime engine. They are used to annotate the code in order to clarify its design and purpose. You can add an unlimited number of comments to a Java file, but there are some "best practices" to follow when using comments.

Generally, code comments are "implementation" comments that explain the ​source code, such as descriptions of classes, interfaces, methods and fields.

These are usually a couple of lines written above or beside Java code to clarify what it does.

Another type of Java comment is a Javadoc comment. Javadoc comments differ slightly in syntax from implementation comments, and are used by the program javadoc.exe to generate Java HTML documentation.

Why Use Java Comments?

It's good practice to get into the habit of putting Java comments into your source code to enhance its readability and clarity for yourself and other programmers. It isn't always instantly clear what a section of Java code is performing. A few explanatory lines can drastically reduce the amount of time it takes to understand the code.

Do They Affect How The Program Runs?

Implementation comments in Java code are only there for humans to read. Java compilers don't care about them and when compiling the program, they just skip over them. The size and efficiency of your compiled program will not be affected by the number of comments in your source code.

Implementation Comments

Implementation comments come in two different formats:

  • Line Comments: For a one line comment, type "//" and follow the two forward slashes with your comment. For example:
     // this is a single line comment
     int guessNumber = (int) (Math.random() * 10); 

    When the compiler comes across the two forward slashes, it knows that everything to the right of them is to be considered as a comment. This is useful when debugging a piece of code. Just add a comment from a line of code you are debugging, and the compiler won't see it: 

     // this is a single line comment
     // int guessNumber = (int) (Math.random() * 10);   

    You can also use the two forward slashes to make an end of line comment:

     // this is a single line comment
     int guessNumber = (int) (Math.random() * 10); // An end of line comment 
  • Block Comments: To start a block comment, type "/*". Everything between the forward slash and asterisk, even if it's on a different line, is treated as a comment until the characters "*/" end the comment. For example:
     /* this 
     is 
     a
     block
     comment
     */
     
     /* so is this */
     

Javadoc Comments

Use special Javadoc comments to document your Java API. Javadoc is a tool included with the JDK that generates HTML documentation from comments in source code.

A Javadoc comment in .java source files is enclosed in start and end syntax like so: /** and */. Each comment within these is prefaced with a *

Place these comments directly above the method, class, constructor or any other Java element that you want to document. For example:

// myClass.java
/**
 * Make this a summary sentence describing your class.
 * Here's another line.
 */

public class ​myClass 
{
...
}

Javadoc incorporates various tags that control how the documentation is generated. For example, the   @param tag defines parameters to a method:

  /** main method
     * @param args String[]
     */​
    public static void main(String[] args)
    ​{
   ​     System.out.println("Hello World!");​
    }

Many other tags are available in Javadoc, and it also supports HTML tags to help control the output.

See your Java documentation for more detail.

Tips for Using Comments

  • Don't over comment. Every line of your program does not need to be explained. If your program flows logically and nothing unexpected occurs, don't feel the need to add a comment.
  • Indent your comments. If the line of code you are commenting is indented, make sure your comment matches the indentation.
  • Keep comments relevant. Some programmers are excellent at modifying code, but for some reason forget to update the comments. If a comment no longer applies, then either modify or remove it.
  • Don't nest block comments. The following will result in a compiler error:
     /* this 
     is
     /* This block comment finishes the first comment */
     a
     block
     comment
     */