Comments & Javadoc

Syntax

// single-line\n/* multi-line */\n/** Javadoc */

Examples

// Calculate the area of a rectangle
int width = 5;
int height = 3;

/*
 * This is a multi-line comment.
 * It can span several lines and is often
 * used for longer explanations.
 */
int area = width * height;
System.out.println(area);

public class MathUtils {
    /**
     * Calculates the average of two numbers.
     *
     * @param a the first number
     * @param b the second number
     * @return the average of a and b
     */
    public static double average(double a, double b) {
        return (a + b) / 2;
    }
}

int total = 0;
for (int i = 1; i <= 10; i++) {
    total += i;
    // System.out.println("Running total: " + total);  // disabled for now
}
System.out.println(total);

Best practices

• Write Javadoc comments for every public class and method so IDEs can show helpful tooltips and documentation tools can generate API docs
• Explain *why* code does something in comments, not *what* it does - the code itself should already communicate the "what"
• Keep comments up to date - an outdated comment that contradicts the code is more harmful than no comment at all
• Use @param, @return, and @throws tags consistently in Javadoc so generated documentation is complete and useful

At a glance

Purpose

General-purpose application development

File extension

.java

Runs in

Java Virtual Machine

Usually used with

JDK and Java libraries

Specifications & further reading

• Java Language Specification

Related Java documentation