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