Comments in Java Code

Comments document code for the purposes of providing information to the current or future programmer. Although comments appear alongside program code, the Java compiler ignores them. They are an important part of Java programming because they help clarify the meaning of code. Beyond the code itself, you really have nothing to describe the mechanics of a program except comments. Comments also come into play if someone else ever inherits your programming efforts. Effective code documentation begins with the three main types of Java comments:

// comment 
/* comment */
/** comment */

1. all characters after // and to the end of the line are ignored
2. all characters between /* and */ are ignored
3. all characters between /** and */ are ignored, and the comment has relevance to the javadoc code documentation tool

The Java SDK includes a code documentation tool called Javadoc that is used to automate the process of documenting your code. The javadoc tool generates code documentation in a web page (HTML) form straight from Java source code comments. The javadoc tool requires you to use some special tags to identify the classes, methods, and variables in your code. Also, the javadoc style comment

(/** */)

must be used in order for the tool to properly generate documentation. The primary benefit to using the javadoc tool is that it completely automates the process of creating code documentation. If you question the effectiveness of automated code documentation, consider the fact that the entire Java API documentation was automatically generated using the javadoc tool.

The third type of comment is a special case of the second. If a comment begins with /**, it is regarded as a special doc comment. Like regular multiline comments, doc comments end with */ and cannot be nested. When you write a Java class you expect other programmers to use, use doc comments to embed documentation about the class and each of its methods directly into the source code. A program named javadoc extracts these comments and processes them to create online documentation for your class. A doc comment can contain HTML tags and can use additional syntax understood by javadoc.
For example:

/**
* Upload a file to a web server.
*
* @param file The file to upload.
* @return true on success,
* false on failure.
* @author Glenn Gould
*/

// comment 
/* comment */
/** comment */

Multiline comments can contain any special characters (including Unicode characters). Here is an example:

class MyClass {
/*
Multi-line comments with
special characters &%^*{}|\|:;"'
?/>.@#$%^&*()
*/
}

Most of the time, when you see a multiline comment in a Java source code file (.java file), you will notice that it uses an asterisk (*) to start the comment in the next line. Please note that this is not required and is done more for aesthetic reasons. Here is an example:

class MyClass {
/*
* comments that span multiple
* lines of code
*/
}

End-of-line comments start with // and, as evident by their name, they are placed at the end of a line of code. The text between // and the end of the line is treated as acomment, which you would normally use to briefly describe the line of code. Here is an example:

class Person {
String fName; // variable to store Person's first name
String id; // a 6 letter id generated by the database

In the earlier section on the package statement, you read that a package statement, if present, should be the first line of code in a class. The only exception to this rule is the presence of comments. A comment can precede a package statement. The following code defines a package statement, with multiline and end-of-line comments:

I have stuck with the first type of comment (//) throughout the course to maintain consistency and keep the code as simple as possible. This type of comment is somewhat limited, however, since it can only be used with a single line of code at a time. The second type of comment (/* */) is more flexible and can be used to comment multiple lines of code. The Java compiler ignores everything that appears between the comment markers (/* */).

class MyClass {
/*
comments that span multiple
lines of code
*/
}