petekp/code-comments

Code Comments

Write documentation that lives with the code it describes. Plain language. No jargon. Explain the why, not the what.

Core Philosophy

Co-location wins. Documentation in separate files drifts out of sync. Comments next to code stay accurate because they're updated together.

Write for three audiences:

1. Future you, six months from now
2. Teammates reading unfamiliar code
3. AI assistants (Claude, Copilot) who see one file at a time

The "why" test: Before writing a comment, ask: "Does this explain why this code exists or why it works this way?" If it only restates what the code does, skip it.

Documentation Levels

File Headers

Every file should open with a brief explanation of its purpose and how it fits into the larger system.

// UserAuthContext.tsx
//
// Manages authentication state across the app. Wraps the root component
// to provide login status, user info, and auth methods to any child.
//
// Why a context instead of Redux: Auth state is read-heavy and rarely
// changes mid-session. Context avoids the ceremony of actions/reducers
// for something this simple.

// NetworkRetryPolicy.swift
//
// Handles automatic retry logic for failed network requests.
// Uses exponential backoff with jitter to avoid thundering herd
// when the server comes back online after an outage.
//
// Used by: APIClient, BackgroundSyncManager
// See also: NetworkError.swift for error classification

Include:

• What this file/module is responsible for
• Why it exists (if not obvious from the name)
• Key relationships to other parts of the codebase
• Any non-obvious design decisions

Function & Method Documentation

Document the contract, not the implementation.

/**
 * Calculates shipping cost based on weight and destination.
 *
 * Uses tiered pricing: under 1lb ships flat rate, 1-5lb uses
 * regional rates, over 5lb triggers freight calculation.
 *
 * Returns $0 for destinations we don't ship to rather than
 * throwing—caller should check `canShipTo()` first if they
 * need to distinguish "free shipping" from "can't ship."
 */
function calculateShipping(weightLbs: number, zipCode: string): number

def sync_user_preferences(user_id: str, prefs: dict) -> SyncResult:
    """
    Pushes local preference changes to the server and pulls remote changes.

    Conflict resolution: server wins for security settings, local wins
    for UI preferences. See PREFERENCES.md for the full conflict matrix.

    Called automatically on app foreground. Can also be triggered manually
    from Settings > Sync Now.
    """

Include:

• What the function accomplishes (not how)
• Non-obvious parameter constraints or edge cases
• What the return value means, especially for ambiguous cases
• Side effects (network calls, file writes, state mutations)

Skip for: Simple getters, obvious one-liners, private helpers with descriptive names.

Inline Comments

Use sparingly. When you need them, explain the reasoning.

// Debounce search by 300ms to avoid hammering the API on every keystroke.
// 300ms feels responsive while cutting API calls by ~80% in user testing.
const debouncedSearch = useMemo(
  () => debounce(executeSearch, 300),
  [executeSearch]
);

// Force unwrap is safe here—viewDidLoad guarantees the storyboard
// connected this outlet. If it's nil, we want to crash immediately
// rather than fail silently later.
let tableView = tableView!

# Process oldest items first. Newer items are more likely to be
# modified again, so processing them last reduces wasted work.
queue.sort(key=lambda x: x.created_at)

Architectural Comments

For code that embodies important design decisions, explain the tradeoffs.

// ARCHITECTURE NOTE: Event Sourcing for Cart
//
// Cart state is rebuilt from events (add, remove, update quantity)
// rather than stored directly. This lets us:
// - Show complete cart history to users
// - Replay events for debugging
// - Retroactively apply promotions to past actions
//
// Tradeoff: Reading current cart state requires replaying all events.
// We cache the computed state in Redis with 5min TTL to keep reads fast.
// Cache invalidation happens in CartEventHandler.

// WHY COORDINATOR PATTERN
//
// Navigation logic lives here instead of in view controllers because:
// 1. VCs don't need to know about each other (loose coupling)
// 2. Deep linking becomes straightforward—just call coordinator methods
// 3. Navigation is testable without instantiating UI
//
// The tradeoff is more files and indirection. Worth it for apps with
// 10+ screens; overkill for simple apps.

TODO Comments

Make them actionable and traceable.

// TODO(pete): Extract to shared util once mobile team needs this too.
// Blocked on: Mobile API parity (see MOBILE-123)

// HACK: Workaround for Safari flexbox bug. Remove after dropping Safari 14.
// Bug report: https://bugs.webkit.org/show_bug.cgi?id=XXXXX

// FIXME: Race condition when user rapidly toggles. Need to cancel
// in-flight requests. Reproduced in issue #892.

Language-Specific Patterns

See references/language-examples.md for detailed examples in:

• TypeScript/JavaScript (JSDoc, TSDoc patterns)
• Swift (documentation comments, MARK pragmas)
• Python (docstrings, type hint documentation)
• React/Next.js (component documentation patterns)

Writing Style

Plain language. Write like you're explaining to a smart colleague who doesn't have context.

Active voice. "This function validates..." not "Validation is performed..."

Be specific. "Retries 3 times with 1s backoff" not "Handles retries."

Skip the obvious. If the code says user.isAdmin, don't comment "checks if user is admin."

Date things that expire. Workarounds, version-specific code, and temporary solutions should note when they can be removed.

Reference constants, don't duplicate values. When a behavior is controlled by a constant, reference it by name—don't restate its value in the comment.

// Bad: duplicates the value, will drift when constant changes
/// Returns true if stale (not updated in last 5 minutes)
pub fn is_stale(&self) -> bool { ... }

// Good: references the constant
/// Returns true if stale (not updated within [`STALE_THRESHOLD_SECS`])
pub fn is_stale(&self) -> bool { ... }

Unit translations for magic numbers are fine (1048576 // 1MB) since they add clarity, not duplication.