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);
}

1. /** — /** (the extra * compared to a regular /* */ comment) opens the ApexDoc convention.
2. * Calculates the commission owed on a real estate sale. — a one-line summary of the method's purpose.
3. * — a blank comment line for spacing.
4. * @param salePrice the final agreed sale price — documents the first parameter.
5. * @param commissionRate the agreed commission percentage (e.g. 5 for 5%) — documents the second parameter.
6. * @return the commission amount — documents the return value.
7. */ — closes the comment block.
8. public Decimal calculateCommission(Decimal salePrice, Decimal commissionRate) { — the method the comment describes.
9. return salePrice * (commissionRate / 100); — its logic.
10. } — closes the method.

This structured shape is 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);

1. // BAD: restates what the code already says — a label for the anti-pattern below.
2. i++; // increment i by 1 — a comment that just repeats what the line obviously does — noise, not value.
3. (blank line)
4. // GOOD: explains something the code alone can't — a label for the good pattern below.
5. // Salesforce processes discounts before tax, so this must run — explains the why: a non-obvious business rule.
6. // before the VAT calculation below, not after. — continues the explanation.
7. applyDiscount(order); — the line the comment is justifying — something 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.