Java Comments & Javadoc: Writing Professional Code Documentation

Comments are non-executable explanatory notes written inside source code to help humans understand the architectural rationale, algorithm constraints, and API contracts of the software.

The 3 Types of Comments in Java

1. Single-Line Comments (//)

Used for brief inline explanations or temporarily toggling a line of code during debugging. The compiler ignores everything from // to the end of that line:

// Define database connection timeout in milliseconds
int timeoutMs = 5000;
int maxRetries = 3; // Maximum reconnect attempts

2. Multi-Line Comments (/* ... */)

Used for longer narrative explanations spanning multiple lines:

/*
 * The following algorithm computes the greatest common divisor (GCD)
 * using Euclid's subtraction algorithm. It guarantees O(log(min(a,b)))
 * time complexity.
 */
public static int gcd(int a, int b) {
    while (b != 0) {
        int temp = b;
        b = a % b;
        a = temp;
    }
    return a;
}

3. Javadoc Comments (/** ... */)

Javadoc comments begin with /** and end with */. They are used immediately before class, interface, method, or constructor declarations to generate formal HTML API documentation:

/**
 * Represents a customer savings account with compound interest calculation.
 * 
 * @author Veewom Engineering Team
 * @version 2.1
 * @since Java 21
 */
public class SavingsAccount {
    private double balance;

    /**
     * Deposits funds into the savings account and updates current ledger.
     *
     * @param amount The monetary amount in USD to deposit (must be > 0).
     * @return The updated total account balance after deposit.
     * @throws IllegalArgumentException if the provided amount is negative or zero.
     */
    public double deposit(double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException("Deposit amount must be positive!");
        }
        this.balance += amount;
        return this.balance;
    }
}

Standard Javadoc Tags Reference