Comments #

// Maximum login attempt limit
int maxAttempts = 3;

int count = 0;
count++; // increment after each failed attempt

// Use an epsilon to avoid floating-point errors
double epsilon = 1e-9;
if (Math.abs(a - b) < epsilon) {
    // Treat as equal if the difference is tiny
}

// ANTI-PATTERN: commenting things that are already obvious from the code
int i = 0;          // set i to 0
i++;                // add 1 to i
list.clear();       // clear the list

// CORRECT: comment the reason (why), not the mechanism (what)
int attempts = 0;
attempts++;         // on each failure, the counter rises before the limit check

list.clear();       // reset state before processing the next batch
                    // don't remove this — needed to avoid stale data

// Timeout reduced by 500ms because of network overhead in the staging environment
int timeoutMs = 4500;

/*
 * This algorithm uses a sliding window approach to find the
 * longest substring without repeating characters. Time complexity is O(n)
 * because each character is processed at most twice.
 */
public int longestUniqueSubstring(String s) {
    Map<Character, Integer> positions = new HashMap<>();
    int max = 0, left = 0;

    for (int right = 0; right < s.length(); right++) {
        char c = s.charAt(right);
        if (positions.containsKey(c) && positions.get(c) >= left) {
            left = positions.get(c) + 1;
        }
        positions.put(c, right);
        max = Math.max(max, right - left + 1);
    }
    return max;
}

/*
// Old code — temporarily disabled during the migration to API v2
Response resp = apiV1.sendRequest(payload);
processResponseV1(resp);
*/

// New code
Response resp = apiV2.sendRequest(payload);
processResponseV2(resp);

/**
 * The first sentence is the summary — shown in indexes and IDE tooltips.
 * The following sentences are the detailed description, which can be as long as needed.
 * Use basic HTML for formatting: {@code code}, <b>bold</b>, <ul><li>list</li></ul>.
 *
 * <p>A new paragraph starts with the &lt;p&gt; tag.</p>
 *
 * @param  paramName  description of the parameter (no type — it's already in the signature)
 * @return            what is returned and the conditions under which it's null
 * @throws SomeException  the condition that causes this exception to be thrown
 * @see    AnotherClass#anotherMethod()  cross-reference to other documentation
 * @since  2.0  the first version where this feature is available
 * @deprecated  use {@link #newMethod()} since version 3.0
 */

/**
 * Represents a bank account with deposit and withdrawal support.
 *
 * <p>All operations that change the balance are thread-safe because they use
 * {@code synchronized}. However, the order of operations between threads is
 * still not guaranteed without external synchronization.</p>
 *
 * <pre>{@code
 * Account account = new Account("BCA-001", 500_000);
 * account.deposit(100_000);
 * account.withdraw(50_000);
 * System.out.println(account.getBalance()); // 550000.0
 * }</pre>
 *
 * @author  Unis Badri
 * @version 1.2
 * @since   1.0
 * @see     TransactionService
 */
public class Account {
    // ...
}

/**
 * Transfers an amount of money from this account to a destination account.
 *
 * <p>The transfer only happens if the source account has enough balance.
 * Both operations (debit and credit) are performed atomically — there is no
 * state where the debit succeeds but the credit fails.</p>
 *
 * @param  destination  the receiving account; must not be {@code null} and must
 *                      not be the same as this account
 * @param  amount       the amount to transfer; must be greater than zero
 * @return              {@code true} if the transfer succeeded,
 *                      {@code false} if the balance is insufficient
 * @throws IllegalArgumentException  if {@code destination} is null, the same
 *                                   as this account, or {@code amount} &lt;= 0
 * @throws AccountLockedException   if either account is currently locked
 * @since  1.1
 */
public boolean transfer(Account destination, double amount) {
    if (destination == null || destination == this) {
        throw new IllegalArgumentException("Invalid destination account");
    }
    if (amount <= 0) {
        throw new IllegalArgumentException("Transfer amount must be positive");
    }
    if (balance < amount) {
        return false;
    }
    this.balance       -= amount;
    destination.balance += amount;
    return true;
}

public class ConnectionConfig {

    /**
     * Maximum number of reconnection attempts before giving up.
     * This value is calibrated against the downstream service SLA — don't
     * raise it without coordinating with the infrastructure team.
     */
    public static final int MAX_RETRY = 5;

    /**
     * Connection timeout in milliseconds.
     *
     * @see #MAX_RETRY
     */
    public static final int TIMEOUT_MS = 3000;

    /**
     * Account number in {@code BANK-XXXX} format where XXXX is
     * four digits. Example: {@code "BCA-0042"}.
     * Must not be {@code null} or empty after object construction.
     */
    private String accountNumber;
}

/**
 * @param  paramName description  — for each method/constructor parameter
 * @return description            — type and conditions of the return value; not for void
 * @throws SomeException reason   — the condition that causes the exception; can be more than one
 * @see    Class#method()         — cross-reference to another class/method
 * @see    <a href="url">text</a> — reference to an external URL
 * @since  version                — the first version it's available
 * @deprecated reason             — marks the API as obsolete + its alternative
 * @author name                   — the author (usually at class level)
 * @version version               — the class version (usually at class level)
 */

/**
 * Examples of inline tags:
 *
 * {@code javaCode}        — renders text as monospace code, HTML-escaped
 * {@link Class#method()}  — hyperlink to another element's documentation
 * {@linkplain Class text} — like @link but with customizable display text
 * {@value CONSTANT}       — inserts the value of a static final constant
 * {@inheritDoc}           — inherits Javadoc from the overridden method
 */

/**
 * Calculates a discount based on the purchase amount.
 *
 * @param  amount total purchase amount in rupiah
 * @return discount percentage between 0.0 and 1.0
 * @deprecated Use {@link #calculateDiscountV2(double, String)} since version 2.0.
 *             This method doesn't consider product category and will
 *             be removed in version 3.0.
 */
@Deprecated(since = "2.0", forRemoval = true)
public double calculateDiscount(double amount) {
    return amount > 1_000_000 ? 0.15 : 0.05;
}

/**
 * Calculates a discount based on the purchase amount and product category.
 *
 * @param  amount    total purchase amount in rupiah
 * @param  category  product category: "electronics", "fashion", or "food"
 * @return discount percentage between 0.0 and 1.0
 * @since  2.0
 */
public double calculateDiscountV2(double amount, String category) {
    // new implementation
}

# Generate documentation for all files in the src/ directory
javadoc -d docs -sourcepath src -subpackages com.example

# Generate with encoding and titles
javadoc \
  -d docs \
  -encoding UTF-8 \
  -docencoding UTF-8 \
  -charset UTF-8 \
  -windowtitle "MyApp API Documentation" \
  -doctitle "MyApp v1.0 API" \
  -sourcepath src \
  -subpackages com.example

# Open the result in your browser
open docs/index.html   # macOS
xdg-open docs/index.html  # Linux

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.6.3</version>
    <configuration>
        <encoding>UTF-8</encoding>
        <show>protected</show>
    </configuration>
</plugin>

# Generate via Maven
mvn javadoc:javadoc

# The result is at target/site/apidocs/index.html

// ✗ ANTI-PATTERN 1: a comment that repeats the code
// Add tax to the total
total = total + tax;

// Check if stock is empty
if (stock == 0) {

// ✗ ANTI-PATTERN 2: a stale, misleading comment
// Returns the user's first name
public String getUsername() {
    return firstName + " " + lastName; // it actually returns the full name
}

// ✗ ANTI-PATTERN 3: commented-out code without any explanation
// if (debug) logger.info("value: " + value);
// return oldProcess(input);
// additionalValidation(x);

// ✗ ANTI-PATTERN 4: TODO comments that are never resolved
// TODO: fix this later
// TODO: handle edge case
// FIXME: this crashes often

// ✗ ANTI-PATTERN 5: a comment explaining "what" instead of "why"
i = i + 1; // add 1 to i

// ✓ CORRECT: comment design decisions and context invisible in the code
// Use LinkedList instead of ArrayList because the main operation here is
// insertion at the middle — O(1) for LinkedList vs O(n) for ArrayList
List<Task> queue = new LinkedList<>();

// The 200ms delay gives the downstream service time to
// finish its commit before we query. Without it, data could be stale.
// See ticket INFRA-4421 for full context.
Thread.sleep(200);

// Negative price validation isn't done here because it's already validated
// at the API layer before reaching this service. If a negative price gets
// through, that's a bug in the API layer, not here.
this.price = price;

/**
 * Searches for products by keyword with pagination.
 *
 * @param  keyword  the search keyword; must not be null, may be empty
 * @param  page     the page number starting from 0 (not 1)
 * @param  size     the number of items per page; max 100
 * @return          the search result page; never null,
 *                  an empty list if there are no results
 */
public Page<Product> search(String keyword, int page, int size) {
    // ...
}