📖 Code Documentation

Writing documentation that developers actually read and use.

Documentation hierarchy

1. Self-documenting code — Clear naming, simple structure
2. Code comments — Explain why, not what
3. README — Setup, architecture overview, quick start
4. API docs — Endpoint reference, request/response schemas
5. Architecture docs — System design, data flows, ADRs

README template

# Project Name

Brief description of what this does.

## Quick start

\`\`\`bash
git clone <repo>
npm install
cp .env.example .env
npm run dev
\`\`\`

## Architecture

Brief overview or link to architecture doc.

## Development

### Prerequisites
- Node.js 20+
- PostgreSQL 16+

### Running tests
\`\`\`bash
npm test
\`\`\`

### Deployment
Link to deployment docs or CI/CD pipeline.

## Contributing

Link to contributing guide.

When to comment

Do comment	Don't comment
Why a non-obvious approach was chosen	What the code does (it should be clear)
Business rules that aren't intuitive	Obvious getter/setter logic
Workarounds with links to issues	Commented-out code (delete it)
Public API contracts (JSDoc)	Every single function
Regex explanations	TODOs without ticket references

JSDoc for public APIs

/**
 * Calculate the total price including tax and discount.
 *
 * @param items - Cart items with quantity and unit price
 * @param taxRate - Tax rate as decimal (e.g., 0.20 for 20%)
 * @param discountCode - Optional promotional discount code
 * @returns Total price in cents
 * @throws {InvalidDiscountError} If the discount code is expired
 */
function calculateTotal(
  items: CartItem[],
  taxRate: number,
  discountCode?: string
): number

API documentation

• Auto-generate from code when possible (OpenAPI/Swagger)
• Include request/response examples
• Document error responses
• Keep in sync with the code (CI check)