Java Comments

// This is a standalone single-line comment

int age = 25; // this is an inline comment — appears after code on the same line

// Multi-word explanation on one line:
// Calculate compound interest using principal * (1 + rate)^years

// Temporarily disable code during debugging:
// System.out.println("debug: value = " + value);

// DON'T — redundant comments that just restate the code:
int count = 0; // set count to zero      ← states the obvious
i++;           // increment i             ← states the obvious

// DO — comments that explain WHY, not WHAT:
int retryCount = 3; // max retries before circuit breaker opens
i += 2;             // skip even indices — only processing odd positions

/* This is a multi-line comment.
   It can span as many lines as needed.
   The compiler ignores everything between the delimiters. */

/*
 * Common style: asterisks on each line for alignment.
 * Not required, just a widely followed convention.
 * Makes multi-line blocks visually clear.
 */

/* Explaining a non-obvious algorithm:
 *
 * This uses Floyd's cycle detection algorithm (tortoise and hare).
 * Two pointers move at different speeds — if there's a cycle,
 * the fast pointer will eventually lap the slow one.
 * Time: O(n), Space: O(1)
 */
ListNode slow = head;
ListNode fast = head;

/* Temporarily comment out a block during debugging: */
/*
processPayment(order);
sendConfirmationEmail(order);
updateInventory(order);
*/

/**
 * Represents a bank account with basic deposit and withdrawal operations.
 *
 * <p>Accounts are identified by a unique account number assigned at creation.
 * All monetary values are in the account's declared currency.</p>
 *
 * @author Alice Johnson
 * @version 2.1
 * @since 1.0
 */
public class BankAccount {

    /**
     * The current balance of this account.
     * Always non-negative; withdrawals that would make it negative are rejected.
     */
    private double balance;

    /**
     * Deposits the specified amount into this account.
     *
     * @param amount  the amount to deposit; must be greater than zero
     * @throws IllegalArgumentException if {@code amount} is zero or negative
     */
    public void deposit(double amount) {
        if (amount <= 0) throw new IllegalArgumentException("Amount must be positive");
        this.balance += amount;
    }

    /**
     * Returns the current balance of this account.
     *
     * @return the current balance, always &gt;= 0
     */
    public double getBalance() {
        return balance;
    }
}

/**
 * @param  name        description of a method parameter
 * @return             description of the return value
 * @throws ExceptionType  conditions under which this exception is thrown
 * @exception ExceptionType  older synonym for @throws
 *
 * @author  name of the author
 * @version current version string
 * @since   version when this was introduced
 * @deprecated  explain why deprecated and what to use instead
 *
 * @see ClassName          link to another class
 * @see ClassName#method   link to a specific method
 * @see <a href="url">text</a>  external link
 *
 * @serial    describes serializable fields
 * @serialData describes serialization data
 *
 * Inline tags (used inside descriptions):
 * {@code value}         renders as monospace code — won't interpret HTML
 * {@link ClassName#method}  hyperlink to another element
 * {@linkplain ClassName text}  hyperlink with custom display text
 * {@inheritDoc}         copies the Javadoc from the overridden method
 * {@literal <text>}    renders angle brackets literally (for generics in prose)
 */

# Generate docs for a single file:
javadoc BankAccount.java

# Generate docs for all files in a package:
javadoc com.example.banking

# Generate with output directory and metadata:
javadoc -d docs/ -author -version -windowtitle "Banking API" src/**/*.java

# Maven generates Javadoc as part of the build:
mvn javadoc:javadoc
# Output appears in: target/site/apidocs/index.html

# Gradle:
./gradlew javadoc
# Output appears in: build/docs/javadoc/index.html

// ── GOOD COMMENTS — explain the non-obvious ─────────────────────

// Using a LinkedList here instead of ArrayList because this queue
// has frequent insertions at the front — O(1) vs O(n)
LinkedList<Task> taskQueue = new LinkedList<>();

// Magic number with explanation:
Thread.sleep(429);  // 429 = HTTP Too Many Requests — wait before retry

// Business rule that isn't obvious from code:
if (user.getAge() >= 18 && user.getCountry().equals("IN")) {
    // KYC required for Indian users 18+ per RBI regulation 2021
    triggerKYCVerification(user);
}


// ── BAD COMMENTS — restate what code already says ────────────────

// Get the user's name
String name = user.getName();     // ← obvious from code

// Loop through the list
for (String item : list) { }      // ← obvious from code

// Add a to b and store in c
int c = a + b;                    // ← obvious from code

// Increment counter
counter++;                        // ← obvious from code


// ── OUTDATED COMMENTS — worse than no comments ────────────────────

// Returns the user's email  ← comment says one thing
public String getUsername() { }   // code does another
// Fix: delete the comment or update it — never leave contradictions