documentation

Documentation SOP

Principle: Document WHY, not WHAT

Good comments explain intent, context, and constraints — not what the code obviously does.

// BAD: restates the code
// increment counter by 1
counter++;

// GOOD: explains non-obvious reason
// Rate limiter uses a sliding window; we increment here to count
// the request before the limit check so abusive callers always
// consume their quota even if the request is rejected.
counter++;

JSDoc / TSDoc Standards

Functions

/**
 * Calculates the user's subscription renewal date based on their billing cycle.
 *
 * @param user - The user whose renewal date to calculate
 * @param referenceDate - The date to calculate from (defaults to now; override in tests)
 * @returns ISO 8601 date string of the next renewal, or null if subscription is cancelled
 * @throws {SubscriptionError} If the user has no active subscription
 *
 * @example
 * const renewalDate = getRenewalDate(user);
 * // → "2025-03-15T00:00:00.000Z"
 */
function getRenewalDate(user: User, referenceDate = new Date()): string | null {
  ...
}

Classes

/**
 * Manages the connection pool for the primary database.
 *
 * Implements exponential backoff on connection failures and
 * automatically reconnects after network interruptions.
 * Not intended for use with read replicas — use ReadReplicaPool for those.
 */
class DatabasePool {
  ...
}

Interfaces / Types

/** Represents a processed payment from the Stripe gateway. */
interface StripePayment {
  /** Stripe payment intent ID (pi_...) */
  intentId: string;
  /** Amount in the smallest currency unit (cents for USD) */
  amountCents: number;
  /** ISO 4217 currency code */
  currency: string;
  /** Unix timestamp of when Stripe confirmed the charge */
  confirmedAt: number;
}

When to Write Inline Comments

Write a comment when:

• A workaround for a third-party library bug is in place (link to the issue)
• Business logic is non-obvious (// Freelancers in DE are taxed differently per §19 UStG)
• A performance optimization would look like an anti-pattern without explanation
• A "why not" explains an approach that was tried and abandoned