Javadoc Best Practices for Spring Boot - 5-Minute Professional Guide 2025

// ❌ BAD: Repeats what the code already says
/**
 * Gets the user name.
 *
 * @return the user name
 */
public String getUserName() {
    return userName;
}

// ✅ GOOD: Omit trivial getters or add useful context
/**
 * Gets the user's display name.
 * 
 * Returns the full name if available, otherwise returns the email username.
 *
 * @return the display name (never null or empty)
 */
public String getUserName() {
    return fullName != null ? fullName : email.split("@")[0];
}

// ❌ BAD: Will break HTML rendering
/**
 * Checks if value is in range [min, max].
 * Returns List of errors.
 */
public boolean inRange(int value, int min, int max) {
    // implementation
}

// ✅ GOOD: Use {@code} to avoid HTML issues
/**
 * Checks if value is in the range {@code [min, max]} (inclusive).
 * 
 * Returns a {@code List} of validation errors if any.
 *
 * @param value the value to check
 * @param min the minimum allowed value (inclusive)
 * @param max the maximum allowed value (inclusive)
 * @return true if value is within range, false otherwise
 */
public boolean inRange(int value, int min, int max) {
    // implementation
}

// ❌ BAD: Unclosed tags break formatting
/**
 * Supported payment types:
 * 
 *   Credit card
 *   Debit card
 *   PayPal
 */
public enum PaymentType {
    // implementation
}

// ✅ GOOD: Always close tags
/**
 * Supported payment types:
 * 
 *   Credit card
 *   Debit card
 *   PayPal
 * 
 *
 * @since 1.0.0
 */
public enum PaymentType {
    // implementation
}

// ❌ BAD: @param only works for methods
/**
 * The user's email address.
 *
 * @param email the email address  // WRONG!
 */
private String email;

// ✅ GOOD: Just describe the field directly
/**
 * The user's email address (must be unique and validated).
 * 
 * Format: {@code username@domain.extension}
 */
private String email;

// ❌ BAD: Exposes implementation (might change)
/**
 * Finds users by email.
 * 
 * Uses a HashMap internally for O(1) lookup performance.
 * Queries the database using Hibernate Criteria API.
 *
 * @param email the email to search
 * @return the user if found
 */
public Optional findByEmail(String email) {
    // implementation
}

// ✅ GOOD: Documents behavior, not implementation
/**
 * Finds a user by their email address.
 * 
 * Email comparison is case-insensitive.
 *
 * @param email the email to search (case-insensitive)
 * @return an optional containing the user if found, or empty otherwise
 */
public Optional findByEmail(String email) {
    // implementation
}

/**
 * $DESCRIPTION$
 *
 * $DETAILS$
 *
 * @param $PARAM$ $PARAM_DESC$
 * @return $RETURN_DESC$
 * @throws $EXCEPTION$ $EXCEPTION_DESC$
 */

/**
 * $DESCRIPTION$
 *
 * $RESPONSIBILITIES$
 *
 * @author $USER$
 * @since $VERSION$
 * @see $RELATED_CLASS$
 */

/**
 * Creates a new $CLASS_NAME$ with the specified $PARAM$.
 *
 * @param $PARAM$ $PARAM_DESC$
 * @throws $EXCEPTION$ if $EXCEPTION_CONDITION$
 */

/**
 * $HTTP_METHOD$ $DESCRIPTION$
 *
 * Endpoint: {@code $HTTP_METHOD$ $ENDPOINT_PATH$}
 *
 * @param $PARAM$ $PARAM_DESC$
 * @return $RETURN_DESC$
 * @throws $EXCEPTION$ if $EXCEPTION_CONDITION$
 */

/**
 * $DESCRIPTION$
 *
 * @param $PARAM$ $PARAM_DESC$
 * @return $RETURN_DESC$
 * @deprecated Use {@link #$REPLACEMENT_METHOD$} instead.
 *             This method will be removed in version $REMOVAL_VERSION$.
 * @see #$REPLACEMENT_METHOD$
 */
@Deprecated

/**
 * Thrown when $CONDITION$.
 *
 * This exception indicates $EXPLANATION$.
 *
 * @author $USER$
 * @since $VERSION$
 * @see $RELATED_EXCEPTION$
 */

package com.devadvisor.payment;

import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

/**
 * Service for processing payment transactions through external payment gateways.
 * <p>
 * This service:
 * <ul>
 *   <li>Validates payment details before processing</li>
 *   <li>Integrates with multiple payment gateways (Stripe, PayPal)</li>
 *   <li>Handles payment failures with automatic retry logic</li>
 *   <li>Sends payment confirmations via email</li>
 * </ul>
 * <p>
 * <b>Transaction Handling:</b> All public methods are transactional and will
 * rollback on any exception.
 * <p>
 * <b>Rate Limiting:</b> Payment processing is subject to rate limiting of
 * {@value #MAX_PAYMENTS_PER_MINUTE} payments per minute per user.
 *
 * @author Imad ALILAT
 * @since 1.0.0
 * @see PaymentGateway
 * @see PaymentValidator
 * @see EmailService
 */
@Service
@RequiredArgsConstructor
@Slf4j
public class PaymentService {

    private final PaymentRepository paymentRepository;
    private final PaymentGateway paymentGateway;
    private final PaymentValidator paymentValidator;
    private final EmailService emailService;
    private final RateLimitService rateLimitService;

    /**
     * Maximum payments allowed per minute per user.
     */
    public static final int MAX_PAYMENTS_PER_MINUTE = 10;

    /**
     * Maximum retry attempts for failed payments.
     */
    private static final int MAX_RETRY_ATTEMPTS = 3;

    /**
     * Processes a payment transaction with automatic retry on transient failures.
     * <p>
     * The payment processing follows these steps:
     * <ol>
     *   <li>Rate limit check for the user</li>
     *   <li>Validation of payment details (amount, card number, CVV)</li>
     *   <li>External gateway processing (Stripe/PayPal)</li>
     *   <li>Database persistence of transaction</li>
     *   <li>Confirmation email to user</li>
     * </ol>
     * <p>
     * <b>Retry Logic:</b> Transient failures (network issues, gateway timeouts)
     * are retried up to {@value #MAX_RETRY_ATTEMPTS} times with exponential backoff.
     * Permanent failures (card declined, insufficient funds) are not retried.
     * <p>
     * <b>Idempotency:</b> If the same payment is submitted multiple times with the
     * same idempotency key, only the first payment is processed. Subsequent requests
     * return the original transaction result.
     *
     * @param payment the payment request containing amount, card details, and idempotency key
     * @param userId the ID of the user making the payment
     * @return the payment result with transaction ID, status, and gateway response
     * @throws RateLimitExceededException if user exceeds {@value #MAX_PAYMENTS_PER_MINUTE} payments per minute
     * @throws InvalidPaymentException if payment validation fails (invalid amount, expired card, etc.)
     * @throws PaymentDeclinedException if the payment is permanently declined by the gateway
     * @throws PaymentGatewayException if the gateway is unavailable after all retry attempts
     * @throws IllegalArgumentException if payment or userId is null
     * @see #refundPayment(String, String, BigDecimal)
     * @see PaymentValidator#validate(Payment)
     */
    @Transactional
    public PaymentResult processPayment(Payment payment, String userId)
            throws RateLimitExceededException, InvalidPaymentException, PaymentDeclinedException {

        log.info("Processing payment for user: {}, amount: {}", userId, payment.getAmount());

        // Validate inputs
        if (payment == null || userId == null) {
            throw new IllegalArgumentException("Payment and userId cannot be null");
        }

        // Check rate limit
        if (!rateLimitService.allowPayment(userId)) {
            log.warn("Rate limit exceeded for user: {}", userId);
            throw new RateLimitExceededException(
                String.format("Rate limit of %d payments per minute exceeded", MAX_PAYMENTS_PER_MINUTE)
            );
        }

        // Validate payment details
        paymentValidator.validate(payment);

        // Process with retry logic
        PaymentResult result = processWithRetry(payment, userId);

        // Send confirmation
        emailService.sendPaymentConfirmation(userId, result);

        log.info("Payment processed successfully. Transaction ID: {}", result.getTransactionId());
        return result;
    }

    /**
     * Refunds a previously processed payment.
     * <p>
     * The refund must meet these conditions:
     * <ul>
     *   <li>Original payment must exist and be in COMPLETED status</li>
     *   <li>Refund amount must not exceed original payment amount</li>
     *   <li>Refund must be requested within 90 days of original payment</li>
     * </ul>
     * <p>
     * <b>Partial Refunds:</b> Multiple partial refunds are supported as long as
     * the total refunded amount doesn't exceed the original payment.
     *
     * @param transactionId the ID of the original payment transaction to refund
     * @param userId the ID of the user requesting the refund (must match original payer)
     * @param amount the amount to refund (must be positive and not exceed remaining balance)
     * @return the refund result with refund ID and updated balances
     * @throws PaymentNotFoundException if no payment exists with the given transaction ID
     * @throws UnauthorizedException if the userId doesn't match the original payer
     * @throws InvalidRefundException if refund conditions are not met
     * @throws PaymentGatewayException if the gateway refund fails
     * @see #processPayment(Payment, String)
     */
    @Transactional
    public RefundResult refundPayment(String transactionId, String userId, BigDecimal amount)
            throws PaymentNotFoundException, InvalidRefundException {

        log.info("Processing refund for transaction: {}, amount: {}", transactionId, amount);

        // Validate refund eligibility
        Payment originalPayment = validateRefundEligibility(transactionId, userId, amount);

        // Process refund with gateway
        RefundResult result = paymentGateway.refund(transactionId, amount);

        // Update database
        paymentRepository.recordRefund(transactionId, result);

        // Send confirmation
        emailService.sendRefundConfirmation(userId, result);

        log.info("Refund processed successfully. Refund ID: {}", result.getRefundId());
        return result;
    }

    /**
     * Retrieves the payment history for a specific user.
     * <p>
     * Results are ordered by payment date (newest first) and include both
     * successful and failed payments.
     * <p>
     * <i>Performance Note:</i> This method is optimized for pagination. For large
     * datasets, use {@link #getPaymentHistory(String, int, int)} instead.
     *
     * @param userId the ID of the user whose payment history to retrieve
     * @return a list of all payments for the user, ordered by date (newest first)
     * @throws IllegalArgumentException if userId is null or empty
     * @see #getPaymentHistory(String, int, int)
     */
    public List getPaymentHistory(String userId) {
        if (userId == null || userId.isBlank()) {
            throw new IllegalArgumentException("User ID cannot be null or empty");
        }

        log.debug("Retrieving payment history for user: {}", userId);
        return paymentRepository.findByUserIdOrderByCreatedAtDesc(userId);
    }

    /**
     * Processes payment with exponential backoff retry logic for transient failures.
     *
     * @param payment the payment to process
     * @param userId the user making the payment
     * @return the payment result
     * @throws PaymentDeclinedException if payment is permanently declined
     * @throws PaymentGatewayException if all retry attempts fail
     */
    private PaymentResult processWithRetry(Payment payment, String userId)
            throws PaymentDeclinedException, PaymentGatewayException {

        for (int attempt = 1; attempt <= MAX_RETRY_ATTEMPTS; attempt++) {
            try {
                return paymentGateway.charge(payment);
            } catch (TransientGatewayException e) {
                log.warn("Payment attempt {} failed for user {}: {}", attempt, userId, e.getMessage());

                if (attempt == MAX_RETRY_ATTEMPTS) {
                    throw new PaymentGatewayException("Payment failed after " + MAX_RETRY_ATTEMPTS + " attempts", e);
                }

                // Exponential backoff: wait 2^attempt seconds
                try {
                    Thread.sleep((long) Math.pow(2, attempt) * 1000);
                } catch (InterruptedException ie) {
                    Thread.currentThread().interrupt();
                    throw new PaymentGatewayException("Payment processing interrupted", ie);
                }
            }
        }

        throw new PaymentGatewayException("Unexpected retry loop termination");
    }

    /**
     * Validates that a refund request meets all eligibility requirements.
     *
     * @param transactionId the transaction to refund
     * @param userId the user requesting refund
     * @param amount the refund amount
     * @return the original payment if eligible
     * @throws PaymentNotFoundException if payment doesn't exist
     * @throws InvalidRefundException if refund conditions aren't met
     */
    private Payment validateRefundEligibility(String transactionId, String userId, BigDecimal amount)
            throws PaymentNotFoundException, InvalidRefundException {

        Payment payment = paymentRepository.findById(transactionId)
            .orElseThrow(() -> new PaymentNotFoundException("Payment not found: " + transactionId));

        if (!payment.getUserId().equals(userId)) {
            throw new UnauthorizedException("User does not own this payment");
        }

        if (payment.getStatus() != PaymentStatus.COMPLETED) {
            throw new InvalidRefundException("Can only refund completed payments");
        }

        if (amount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new InvalidRefundException("Refund amount must be positive");
        }

        if (amount.compareTo(payment.getRemainingBalance()) > 0) {
            throw new InvalidRefundException("Refund amount exceeds remaining balance");
        }

        LocalDateTime paymentDate = payment.getCreatedAt();
        LocalDateTime ninetyDaysAgo = LocalDateTime.now().minusDays(90);
        if (paymentDate.isBefore(ninetyDaysAgo)) {
            throw new InvalidRefundException("Refund window expired (90 days)");
        }

        return payment;
    }
}