Comment & Documentation Standards¶

Status: 🟢 Active  |  Owner: Engineering Enablement

Overview¶

Good code is largely self-documenting. Comments should explain why, not what. The code shows what — a comment explains intent, trade-offs, or constraints that cannot be expressed in the code itself.

When to Comment¶

✅ Do comment: - Non-obvious business rules or regulatory constraints - Performance trade-offs and the reasoning behind them - Workarounds for known third-party bugs (include issue tracker link) - Complex algorithms — a brief explanation and link to the reference - Public API surfaces (all public methods/functions must have doc comments)

❌ Do not comment: - What the code obviously does (// increment counter) - Commented-out code (delete it — use git history) - TODO comments without a linked ticket (// TODO: fix this is forbidden)

Doc Comment Standards by Language¶

Java (Javadoc)¶

/**
 * Calculates the total price for an order including applicable taxes.
 *
 * <p>Tax rates are fetched from the {@link TaxService} and cached for 5 minutes.
 * For zero-rated items, the tax calculation is skipped entirely.
 *
 * @param order the order to calculate; must not be null
 * @param locale the locale used to determine applicable tax rules
 * @return the total price including tax, never negative
 * @throws TaxCalculationException if the tax service is unavailable
 */
public Money calculateTotal(Order order, Locale locale) { ... }

Python (Google-style docstrings)¶

def calculate_total(order: Order, locale: str) -> Decimal:
    """Calculates the total price for an order including applicable taxes.

    Tax rates are fetched from the TaxService and cached for 5 minutes.

    Args:
        order: The order to calculate. Must not be None.
        locale: The locale string used to determine applicable tax rules.

    Returns:
        The total price including tax as a Decimal. Never negative.

    Raises:
        TaxCalculationError: If the tax service is unavailable.
    """

TypeScript (TSDoc)¶

/**
 * Calculates the total price for an order including applicable taxes.
 *
 * @param order - The order to calculate. Must not be null.
 * @param locale - The locale used to determine applicable tax rules.
 * @returns The total price including tax. Never negative.
 * @throws {TaxCalculationError} If the tax service is unavailable.
 */
function calculateTotal(order: Order, locale: string): Money { ... }

Go¶

// CalculateTotal returns the total price for an order including applicable
// taxes. Tax rates are fetched from the TaxService and cached for 5 minutes.
// Returns an error if the tax service is unavailable.
func CalculateTotal(order Order, locale string) (Money, error) { ... }

TODO / FIXME Policy¶

All TODO and FIXME comments must reference a tracked issue:

# TODO(JIRA-1234): Remove this workaround once upstream bug is fixed
# FIXME(JIRA-5678): This O(n²) loop is a performance risk for large datasets

CI will fail on any TODO or FIXME without a ticket reference pattern.

Last reviewed: 2025-Q4  |  Owner: Engineering Enablement