Apex Documentation

ApexDoc Standards

Required Documentation Elements

All public and protected classes and methods must have ApexDoc comments.

For Classes:

• @description - Brief description followed by expanded details explaining the class purpose, context, and role in the application
• Key functionalities - Bulleted list of main features/capabilities provided by the class
• Additional context - Explanation of how the class interacts with other classes and its role in the system
• @author - Comma-separated list of version control users who have contributed to the class
• @since - Include only meaningful milestones that help maintainers understand notable history
• @see - References to related classes/methods with brief descriptions of the relationship
• Code examples (when helpful) - Usage examples in <pre> tags

For Methods:

• Description - Plain text description of what the method does (no @description tag, just the description text)
• @param - Parameter descriptions (for each parameter, one per line)
• @return - Return value description with type in backticks (format: `Type` Description)
• @throws - Exceptions that may be thrown with conditions
• @see - References to related classes/methods (when applicable, one per line)

ApexDoc Comment Format

Use the required elements above as the baseline shape for class and method docs.

/**
 * @description Service class for managing Account records.
 *
 * Key functionalities:
 * - Creating and validating Account records
 * - Updating Accounts through a consistent service interface
 *
 * Additional context:
 * - Works with ACME_AccountSelector for queries.
 * - Used by trigger handlers and controller-layer services.
 *
 * @author contributor1, contributor2
 * @since 01-01-2024 Initial implementation - contributor1
 * @see ACME_AccountTriggerHandler Trigger entry points for Account operations
 * @see ACME_AccountSelector Query and data-access layer
 *
 * Example usage:
 * <pre>
 * ACME_AccountService.createAccount('Test Account');
 * </pre>
 */
public class ACME_AccountService {
}

/**
 * Creates a new Account record with the specified name.
 * @param accountName The name for the new account.
 * @return `Account` The created Account record.
 * @throws ACME_ValidationException if accountName is null or blank.
 * @see ACME_AccountService.updateAccount
 */
public static Account createAccount(String accountName) {
    // Implementation
}

Optional but Recommended Tags

Use these tags when they improve maintainability or clarify usage.

/**
 * @description Runs the Account query via the selector and packages rows for list response rendering.
 * @param filterCriteria Filters for the Account query (for example industry, owner).
 * @param fieldNameType Map of field API names to display data types.
 * @param columnReferenceFields Map of field API names to related label fields for reference columns.
 * @param additionalFields Extra Account fields to include in each row.
 * @return `Map<String, List<FieldWrapper>>` Field name to cell values for the grid or list.
 * @throws ACME_ValidationException if filterCriteria is null or invalid.
 * @see ACME_AccountService
 * @see ACME_AccountSelector
 *
 * Example:
 * <pre>
 * List<Account> accounts = ACME_AccountSelector.selectActiveAccounts();
 * </pre>
 */

Inline Comments Guidelines

• Prefer self-documenting code - Use clear variable and method names
• Add comments when logic is complex - Explain "why" not "what"
• Avoid obvious comments - Don't restate what the code clearly shows
• Update comments with code changes - Keep comments in sync with code

Good Example:

// Use safe navigation to avoid NPE when record type is null
String objectName = record?.getSObjectType()?.getDescribe()?.getName();

Bad Example:

// Set the account name
account.Name = 'Test';

Change History

Version 1.0 - 2026-03-26

• Added initial version history tracking for this document.

Last Updated: 2026-03-26 Version: 1.0