Code Documentation
README Structure
Standard README Template
markdown
# Project Name
Brief description of what this project does.
## Quick Start
\`\`\`bashnpm installnpm run dev\`\`\`
## Installation
Detailed installation instructions...
## Usage
\`\`\`typescriptimport { something } from 'project';
// Example usageconst 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:**\`\`\`typescriptconst result = functionName('value');\`\`\`
## Configuration
| Option | Type | Default | Description ||--------|------|---------|-------------|| `option1` | `string` | `'default'` | What it does |
## Contributing
How to contribute...
## License
MITAPI Documentation
JSDoc/TSDoc Style
typescript
/** * 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: '[email protected]', * 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
yaml
openapi: 3.0.0info: 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-timeInline Comments
When to Comment
typescript
// 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
typescript
// BAD: Stating the obvious// Increment counter by 1counter++;
// BAD: Explaining clear code// Check if user is adminif (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)
markdown
# ADR-001: Use PostgreSQL for Primary Database
## StatusAccepted
## ContextWe need a database for storing user data and transactions.Options considered: PostgreSQL, MySQL, MongoDB, DynamoDB.
## DecisionUse 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 featuresComponent Documentation
markdown
## Authentication Module
### OverviewHandles user authentication using JWT tokens with refresh rotation.
### Flow1. User submits credentials to `/auth/login`2. Server validates and returns access + refresh tokens3. 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 lifetimeDocumentation 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
