ApexDoc and Documentation Standards

/**
 * Calculates the commission owed on a real estate sale.
 *
 * @param salePrice the final agreed sale price
 * @param commissionRate the agreed commission percentage (e.g. 5 for 5%)
 * @return the commission amount
 */
public Decimal calculateCommission(Decimal salePrice, Decimal commissionRate) {
    return salePrice * (commissionRate / 100);
}

/** ... */ above a method (note the extra * compared to a regular /* */ comment) is the ApexDoc convention — a structured way to describe what a method does, its parameters, and what it returns, readable by both humans and documentation-generating tools.

// BAD: restates what the code already says
i++; // increment i by 1

// GOOD: explains something the code alone can't
// Salesforce processes discounts before tax, so this must run
// before the VAT calculation below, not after.
applyDiscount(order);

A comment that just repeats what the next line obviously does adds noise, not value. The comments worth writing explain the why — a business rule, a non-obvious ordering requirement, a workaround — things a reader genuinely couldn't infer from the code alone.

Apex compiles identically whether or not a method has an ApexDoc block above it — this is a team and community convention, not a language rule. Well-documented public methods (the ones other developers will actually call) tend to matter most; small private helper methods with a clear name often need no comment at all.