Code Documentation
README Structure
Standard README Template
# Project Name
Brief description of what this project does.
## Quick Start
\`\`\`bash
npm install
npm run dev
\`\`\`
## Installation
Detailed installation instructions...
## Usage
\`\`\`typescript
import { something } from 'project';
// Example usage
const result = something.doThing();
\`\`\`
## API Reference
### `functionName(param: Type): ReturnType`
Description of what the function does.
**Parameters:**
- `param` - Description of parameter
**Returns:** Description of return value
**Example:**
\`\`\`typescript
const result = functionName('value');
\`\`\`
## Configuration
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option1` | `string` | `'default'` | What it does |
## Contributing
How to contribute...
## License
MIT
API Documentation
JSDoc/TSDoc Style
/**
* Creates a new user account.
*
* @param userData - The user data for account creation
* @param options - Optional configuration
* @returns The created user object
* @throws {ValidationError} If email is invalid
* @example
* ```ts
* const user = await createUser({
* email: 'user@example.com',
* name: 'John'
* });
* ```
*/
async function createUser(
userData: UserInput,
options?: CreateOptions
): Promise<User> {
// Implementation
}
/**
* Configuration options for the API client.
*/
interface ClientConfig {
/** The API base URL */
baseUrl: string;
/** Request timeout in milliseconds @default 5000 */
timeout?: number;
/** Custom headers to include in requests */
headers?: Record<string, string>;
}
OpenAPI/Swagger
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/users:
post:
summary: Create a user
description: Creates a new user account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInput'
responses:
'201':
description: User created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Invalid input
components:
schemas:
UserInput:
type: object
required:
- email
- name
properties:
email:
type: string
format: email
name:
type: string
User:
type: object
properties:
id:
type: string
email:
type: string
name:
type: string
createdAt:
type: string
format: date-time
Inline Comments
When to Comment
// GOOD: Explain WHY, not WHAT
// Use binary search because the list is always sorted and
// can contain millions of items - O(log n) vs O(n)
const index = binarySearch(items, target);
// GOOD: Explain complex business logic
// Users get 20% discount if they've been members for 2+ years
// AND have made 10+ purchases (per marketing team decision Q4 2024)
if (user.memberYears >= 2 && user.purchaseCount >= 10) {
applyDiscount(0.2);
}
// GOOD: Document workarounds
// HACK: Safari doesn't support this API, fallback to polling
// TODO: Remove when Safari adds support (tracking: webkit.org/b/12345)
if (!window.IntersectionObserver) {
startPolling();
}
When NOT to Comment
// BAD: Stating the obvious
// Increment counter by 1
counter++;
// BAD: Explaining clear code
// Check if user is admin
if (user.role === 'admin') { ... }
// BAD: Outdated comments (worse than no comment)
// Returns the user's full name <-- Actually returns email now!
function getUserIdentifier(user) {
return user.email;
}
Architecture Documentation
ADR (Architecture Decision Record)
# ADR-001: Use PostgreSQL for Primary Database
## Status
Accepted
## Context
We need a database for storing user data and transactions.
Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB.
## Decision
Use PostgreSQL with Supabase hosting.
## Rationale
- Strong ACID compliance needed for financial data
- Team has PostgreSQL experience
- Supabase provides auth and realtime features
- pgvector extension for future AI features
## Consequences
- Need to manage schema migrations
- May need read replicas for scale
- Team needs to learn Supabase-specific features
Component Documentation
## Authentication Module
### Overview
Handles user authentication using JWT tokens with refresh rotation.
### Flow
1. User submits credentials to `/auth/login`
2. Server validates and returns access + refresh tokens
3. Access token used for API requests (15min expiry)
4. Refresh token used to get new access token (7d expiry)
### Dependencies
- `jsonwebtoken` - Token generation/validation
- `bcrypt` - Password hashing
- `redis` - Refresh token storage
### Configuration
- `JWT_SECRET` - Secret for signing tokens
- `ACCESS_TOKEN_EXPIRY` - Access token lifetime
- `REFRESH_TOKEN_EXPIRY` - Refresh token lifetime
Documentation Principles
- Write for your audience - New devs vs API consumers
- Keep it close to code - Docs in same repo, near relevant code
- Update with code - Stale docs are worse than none
- Examples over explanations - Show, don't just tell
- Progressive disclosure - Quick start first, details later
plurigrid