Java Fundamentals

Comments & Javadoc

15 min Lesson 8 of 14

Comments & Javadoc

Code is written once but read many times — by your future self, by teammates, and by tools. Comments and Javadoc are the primary way Java developers communicate intent inside source files. In this lesson you will learn every comment style Java supports, when to use each one, and how to write professional API documentation with Javadoc tags.

Line Comments

A line comment starts with // and runs to the end of the line. Use it to explain a single statement or to leave a short note.

int speed = 60; // kilometres per hour, not miles

// Multiply by 1000 to convert km to metres
double distanceMetres = speed * 1000.0;

Line comments are ideal for brief, local explanations. Keep them short — if a comment needs multiple sentences, a block comment is usually cleaner.

Block Comments

A block comment opens with /* and closes with */. Everything between those delimiters is ignored by the compiler, regardless of how many lines it spans.

/*
  This method converts a temperature value from Celsius to Fahrenheit.
  Formula: F = (C * 9/5) + 32
  Input must be a valid double; no bounds checking is performed.
*/
double toFahrenheit(double celsius) {
    return (celsius * 9.0 / 5.0) + 32.0;
}

Block comments are great for temporarily disabling code during debugging. Wrap the section in /* ... */, test, then remove the comment. Just be careful not to leave commented-out code in production — version control is the right place for old code.

Javadoc Comments

Javadoc comments start with /** (two asterisks) and close with */. They are placed directly above a class, interface, constructor, method, or field declaration. The javadoc tool reads these comments and generates HTML documentation — the same HTML you see on the official Java API site (docs.oracle.com).

/**
 * Represents a bank account that supports deposits and withdrawals.
 *
 * @author  Edrees Salih
 * @version 1.0
 * @since   17
 */
public class BankAccount {

    /** The current balance; always >= 0. */
    private double balance;

    /**
     * Creates a new account with the given opening balance.
     *
     * @param initialBalance  the starting balance; must be >= 0
     * @throws IllegalArgumentException if {@code initialBalance} is negative
     */
    public BankAccount(double initialBalance) {
        if (initialBalance < 0) {
            throw new IllegalArgumentException("Balance cannot be negative.");
        }
        this.balance = initialBalance;
    }

    /**
     * Deposits the specified amount into the account.
     *
     * @param  amount  the amount to deposit; must be > 0
     * @return the new balance after the deposit
     * @throws IllegalArgumentException if {@code amount} is not positive
     */
    public double deposit(double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException("Deposit amount must be positive.");
        }
        balance += amount;
        return balance;
    }
}

Common Javadoc Tags

Tags always appear inside a /** ... */ block and start with @. The most important ones are:

@param name description — documents one method parameter.
@return description — describes the return value (omit for void methods).
@throws ExceptionType description — documents a checked or runtime exception the method can throw.
@author name — records the author (class-level only).
@version text — records the version (class-level only).
@since text — notes the Java version or product version this API was introduced.
{@code expression} — inline tag; renders as monospace without HTML-processing the content.
{@link ClassName#method} — creates a clickable cross-reference in the generated HTML.

Javadoc is for the public API. Private fields and package-private helpers rarely need Javadoc — they are implementation details. Reserve Javadoc for public and protected members that other developers will call.

Writing Self-Documenting Code

The best comment is often no comment at all — because the code itself is clear enough. Self-documenting code uses meaningful names, small focused methods, and well-chosen constants so that a reader can understand the intent without stopping to read a comment.

// HARD TO READ — requires a comment to understand the magic number
if (statusCode == 3) { // 3 means "shipped"
    notifyCustomer();
}

// SELF-DOCUMENTING — no comment needed
final int SHIPPED = 3;
if (statusCode == SHIPPED) {
    notifyCustomer();
}

Similarly, a method named calculateMonthlyInterest(double principal, double annualRate) tells you everything without a comment. A method named calc(double a, double b) forces you to read its body.

Avoid redundant comments. A comment that merely restates the code adds noise and becomes a maintenance burden — it must be updated every time the code changes. Write comments that explain why, not what.

Generating the HTML Docs

Run the javadoc command from the terminal to turn your comments into a browsable website:

javadoc -d docs src/BankAccount.java

The -d docs flag sets the output directory. Open docs/index.html in a browser to see your formatted documentation. IDEs like IntelliJ IDEA also show Javadoc inline in tooltips as you type.

Summary

Use // for short one-line notes, /* ... */ for multi-line explanations or temporary code removal, and /** ... */ Javadoc for all public API members. Invest in descriptive names so your code reads like prose, and reserve comments for explaining why a decision was made — not what the code does. Good documentation is a mark of professional Java development.