int timeout = 30; // seconds, not milliseconds
Everything after the two slashes is ignored until the newline. You can place one on its own line above code, or after code on the same line. There is no block form of a single-line comment and no way to end it early.
/* This comment
can span many
lines and stops only at the first star-slash. */
The closing token is the first star-slash that appears. That word "first" is the source of the biggest gotcha in this topic.
/**
* Adds two numbers.
* @param a first operand
* @return the sum
*/
The extra star is what makes this a documentation comment rather than an ordinary block comment. The javadoc tool reads these and produces HTML. They must sit directly above a class, method, field, or constructor with no blank line in between.
Block comments do not nest. The first star-slash closes the comment, whatever follows is treated as code. So this fails to compile:
/* trying to disable this
/* and this too */
System.out.println("unreachable"); */
The comment ends at the first star-slash, and the remaining text is parsed as Java, producing an error. The workaround is to replace the inner pair with line comments, or to delete rather than nest.
int result = /* inline */ a + b;
System.out.println(/* separator */ label + value);
This compiles, and it is occasionally useful for annotating a confusing expression. Readability usually suffers, so use it sparingly.
@param names a parameter and should match the signature exactly. @return describes the returned value and is omitted from void methods. @throws documents a checked exception that may be thrown. @since marks the version an member appeared in. @see cross-references another class or method. @author and @version are conventional in headers. @deprecated flags a member that should no longer be used, and since Java 9 you also have @deprecatedForRemoval, which generates a removal warning for callers.
Run the tool against your source:
javadoc -d docs src/com/example/Calculator.java
You get HTML pages, an index, a search box, and cross-linked types. Modern builds run it through Maven or Gradle automatically, and the doclint tool checks your comments for errors such as a malformed tag or a @param for a parameter that does not exist. Enable it with -Xdoclint:all when you want to catch broken documentation in a build.
javac removes every comment before producing bytecode. A class with heavy documentation and the same class with no comments at all produce functionally identical bytecode. So commenting code out while debugging costs nothing at run time, but leaving dead commented code behind confuses the next person who reads the file.
Do not write a comment that restates the code. int count = 0; followed by // count is set to 0 tells a reader nothing. Comment the reason instead: // reset because the parser reuses this buffer between records. The useful signal is the intent the code cannot express, such as why an unusual constant was chosen or which bug a workaround is guarding against.
Two extra forms matter when writing tests or data files. Text blocks using triple double quotes, and // or /* */ inside a string literal, are just characters to the compiler. That also means a commented-out snippet containing a string with slashes can close a block comment early, which is another reason to delete dead code rather than keep it commented.
import java.util.List;
import java.util.ArrayList;
/**
* Demonstrates every comment syntax Java supports.
*
* <p>This block is a Javadoc comment because it opens with two stars.
* The javadoc tool turns it into HTML.</p>
*
* @author Tanmoy
* @since 1.0
*/public class CommentDemo {
/** Timeout used by the retry logic, in seconds. */ private static final int TIMEOUT = 30;
// A single-line comment sitting above a field.
// Repeated lines are perfectly legal.
/*
* A multi-line comment. It runs until the first star-slash,
* no matter how long it gets.
*/ private static final String label = "Calculator";
/**
* Adds two integers.
*
* @param a the first operand
* @param b the second operand
* @return the sum of a and b
* @throws IllegalArgumentException if either operand is negative
*/ public static int add(int a, int b) {
if (a < 0 || b < 0) {
throw new IllegalArgumentException("operands must be non-negative");
} return a + b;
// trailing single-line comment
} // 1) Block comments may sit inside an expression
public static int combine(int a, int b) {
return a /* left */ + /* operator */ b;
} // 2) A comment inside a string is just text, not a comment
public static String notAComment() {
return "// this is not a comment /* neither is this */";
} // 3) Text blocks hold characters that would otherwise be comments
public static String textBlock() {
return """
// this line is part of the string
block comment inside a text block: /* still text */
""";
} /*
* 4) Block comments do NOT nest. This whole class compiles because
* the inner pair below is written as line comments instead:
*/ public static void nestingDemo() {
// int removed = 1;
// /* also removed */ String name = "gone";
System.out.println("nesting demo ran");
} /**
* Builds the list used by {@link #add(int, int)} style cross-references.
*
* @return a list holding the label
* @deprecated use {@link #label()} instead
*/ @Deprecated public static List<String> buildList() {
List<String> items = new ArrayList<>();
items.add(label);
return items;
} public static String label() {
return label;
} public static void main(String[] args) {
System.out.println("timeout=" + TIMEOUT);
System.out.println("add(10,20)=" + add(10, 20));
System.out.println("combine(10,20)=" + combine(10, 20));
System.out.println("notAComment=" + notAComment());
System.out.println("textBlock:");
System.out.print(textBlock());
nestingDemo();
System.out.println("buildList=" + buildList());
// 5) try-with-resources is safer than commenting code out
try(java.io.BufferedReader r = new java.io.BufferedReader(new java.io.StringReader("data"))) {
System.out.println("first line=" + r.readLine());
} catch (java.io.IOException e) {
// 6) catching and ignoring is only acceptable when nothing can be done
}
}
}// --- Expected console output ---
// timeout=30
// add(10,20)=30
// combine(10,20)=30
// notAComment=// this is not a comment /* neither is this */
// textBlock:
// // this line is part of the string
// block comment inside a text block: /* still text */
// nesting demo ran
// buildList=[Calculator]
// first line=data