Write clear, plain-spoken code comments and documentation that lives alongside the code. Use when writing or reviewing code that needs inline documentation—file headers, function docs, architectural decisions, or explanatory comments. Optimized for both human readers and AI coding assistants who ben

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. 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. 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. Architectural Comments For code that embodies important design decisions, explain the tradeoffs. TODO Comments Make them actionable and traceable. Language Specific Patterns See [references/language examples.md](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. Unit translations for magic numbers are fine ( 1048576 // 1MB ) since they add clarity, not duplication.

code-comments