Commenting Philosophy

TLDR

Comment as if every future AI session starts with zero context. Heavy comments on business logic. Docstrings on every function. Section markers in large files. This isn't overhead — it's how you keep AI consistent across sessions without re-explaining everything.

Who Comments Are For

In AI-assisted development, comments serve three audiences: future you, future human collaborators, and AI in future sessions. The third audience is new, and it changes how you should comment.

Every future AI session re-reads your codebase from scratch. Your comments are instructions for that session. Missing comments = AI makes fresh assumptions that may contradict earlier decisions.

Docstrings on Every Function

/**
 * Validates and creates a new user account.
 *
 * Business logic:
 * - Email must be unique (throws 409 if duplicate)
 * - Password hashed with bcrypt before storage
 * - Returns JWT token on success, NOT the user object
 * - Sends welcome email async (non-blocking)
 *
 * @param email - User's email address
 * @param password - Plain text password (hashed internally)
 * @returns JWT token string
 * @throws 409 if email already registered
 * @throws 422 if validation fails
 */
async function createUser(email: string, password: string): Promise<string>

Business Logic Needs the Most

Comments don't need to explain what (the code shows that). They need to explain why — the decisions, constraints, edge cases, and intentional choices that aren't obvious from the code.

// We use JSONB here intentionally — each tool type has
// different config fields. Normalising this would require
// a new table per tool type, which is over-engineered for MVP.
// See ARCHITECTURE.md §Tool Configuration for the full rationale.
config JSONB NOT NULL DEFAULT ''

Section Markers for Large Files

// ============================================================
// AUTH MIDDLEWARE
// Validates JWT token. Called before any protected route.
// See /src/lib/auth.ts for token generation.
// ============================================================

// ============================================================
// USER ROUTES
// ============================================================

AI scanning a 400-line file finds the right section instantly with these markers. Without them, it reads the whole file and still might miss the relevant section.

What NOT to Comment

Don't comment obvious code:

// BAD: Increment counter
counter++;

// BAD: Return the user
return user;

This adds noise without value. Comment the why, not the what.

Instructing AI to Comment

Add to your .clinerules:

## Commenting Standards
- Every function/method must have a docstring
- Business logic must explain WHY, not just what
- Use section markers in files over 100 lines
- Reference related files when relevant
- DO NOT comment obvious code

AI will follow these rules on every task. You don't need to ask — it's in the contract.