Documentation & Commenting Standards

---
description: Standards for writing clear project documentation and meaningful comments that explain the "why" behind the code.
globs: "**/*.md,**/*.mdx,**/*.js,**/*.jsx,**/*.ts,**/*.tsx,**/*.py,**/*.go,**/*.rb"
alwaysApply: true
---

# Documentation & Commenting Standards

## Core Philosophy
- Treat documentation as a first-class part of the codebase
- Prioritize explaining *intent* and *reasoning* over describing *what* the code does
- Keep docs close to the code so they evolve together

## Commenting Principles
- **Explain *Why***: Capture decision rationale, edge cases, and assumptions
- **Be Concise**: Use clear language; avoid restating obvious implementation details
- **Stay Current**: Update or remove comments when code changes render them obsolete
- **Use TODO with Context**: `// TODO(author yyyy-mm-dd): rationale …` so follow-ups are traceable

## Documentation Types & Locations
| Type | Purpose | Location |
|------|---------|----------|
| README | Project overview, setup, run & test instructions | `project-root/README.md` |
| Architecture Decision Records (ADR) | Record significant technical decisions | `docs/adr/NNNN-title.md` |
| Module Docs | Describe public APIs, usage examples | `src/<module>/README.md` |
| Inline Code Comments | Clarify non-obvious logic, algorithms, workarounds | In code above the relevant lines |
| Changelogs | Document user-facing changes per release | `CHANGELOG.md` |

## Best Practices
- Use Markdown headings (`##`, `###`) to create a clear outline
- Prefer bullet lists and tables for readability
- Co-locate small docs (`README.md`) with code modules to reduce navigation friction
- For ADRs use the template:
  ```markdown
  # Status
  Accepted (yyyy-mm-dd)

  # Context
  ...why the decision was needed…

  # Decision
  ...the choice made…

  # Consequences
  ...positive/negative ramifications…
  ```
- For public functions/classes include JSDoc / docstring blocks:
  ```ts
  /**
   * Calculates the shipping cost based on weight & distance.
   * @param weightKg – parcel weight in kilograms
   * @param km – distance in kilometres
   * @returns cost in USD
   */
  export function calcShippingCost(weightKg: number, km: number): number { … }
  ```

## Automation & Tooling
- Enforce JSDoc / docstring coverage via linters (e.g., `eslint-plugin-jsdoc`, `pydocstyle`)
- Run `markdownlint` in CI to catch style issues
- Generate API reference docs from typed source (TypeDoc, Sphinx, GoDoc)
- Block PR merge if ADR directory or CHANGELOG is missing for significant changes

## Implementation Notes
- Keep docs DRY: link to shared sections instead of duplicating content
- Use diagrams (PlantUML, Mermaid) where visuals clarify complex flows
- Review documentation during code reviews just like code
- Schedule quarterly “documentation days” to pay down doc debt