Code Comments

Quick Reference

• When to use: Writing or reviewing code comments
• Enforcement: ESLint (jsdoc plugin) + Code Review
• Impact if violated: High - inconsistent documentation and confusion

The Rule

Git history is the source of truth for code evolution. Comments explain WHY, not WHAT.

NEVER explain removed code in comments. Delete outdated comments about previous implementations, deprecated features, or removed architecture. Use git log and git blame to understand historical context.

Core Principles

1. Git Is Source of Truth - Removed code? Check git history
2. Comments Explain "Why," Not "What" - Code shows WHAT, comments explain WHY
3. Delete, Don't Deprecate - Remove dead code completely, trust version control

Comment Types

Type	Syntax	Use Case	Example
JSDoc Block	/** */	Functions, interfaces, classes, type aliases	Parameter docs, return types
Single-line	//	Inline explanations, brief context	Business logic "why"
Coverage Ignore	/* v8 ignore */	Skip coverage for specific lines/blocks	AWS SDK wrappers
Format Override	// fmt: multiline	Force multiline arrays/objects	Test fixtures
dprint Ignore	// dprint-ignore	Skip formatting for statement	Matrix data

JSDoc/TSDoc Standards

Required For

• All exported functions with business logic
• All interfaces and type aliases that are part of package public API
• Lambda handler entry points

NOT Required For

• Test files - ESLint relaxes JSDoc rules for **/test/**/*.ts
• Thin wrapper functions (5 lines or fewer body)
• Simple utility functions with self-documenting signatures
• Re-export barrel files (index.ts with only exports)

Format

/**
 * Brief description of what the function does.
 *
 * Additional context explaining WHY, if needed.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws {ErrorType} When this error occurs
 */

Rules

• Hyphen required after @param name (TSDoc standard): @param name - Description
• No types in JSDoc - TypeScript provides types (jsdoc/no-types is an error)
• Don't restate parameter names as descriptions
• TypeScript types serve as primary documentation; @param and @returns tags are optional

Example

/**
 * Validates user credentials against the authentication service.
 *
 * Uses Better Auth for OAuth token validation. The auth instance
 * is obtained via @mantleframework/auth vendor wrapper.
 *
 * @param username - User's email or username
 * @param password - Plain text password (will be hashed)
 * @returns Promise resolving to authenticated user or null
 * @throws {AuthenticationError} If service is unavailable
 */
async function authenticate(username: string, password: string): Promise<User | null>

Single-Line Comments

Style Rules

Rule	Status	Example
Space after //	Required	// Comment not //Comment
Capitalize first letter	Preferred	Lowercase OK for very short notes
No period for single sentences	Required	// This is a comment
Period for multi-sentence	Required	// First sentence. Second sentence.

Good Examples

// Parallelize independent operations for ~60% latency reduction
const results = await Promise.allSettled([op1(), op2()])

// Extract userId from JWT claims
const userId = claims.sub

Bad Examples

//no space after slash
// Ends with period for single sentence.
// We used to validate email here but moved it to middleware  // Don't explain history

What NOT to Comment

Forbidden Patterns

// We used to validate email here but moved it to middleware
// Previously this used callbacks, now uses promises
// Old version - keep for reference
// Increment counter by 1
counter++

Why These Are Bad

• Removed code explanations - Use git log -p path/to/file.ts
• Version history - Use git log
• Obvious operations - Code is self-documenting
• TODO without context - Use ticket links or describe the action needed

Coverage Ignore Patterns

Standard Format

/* v8 ignore start - [reason] */
// ... code to ignore
/* v8 ignore stop */

// Or for single lines:
/* v8 ignore next */
const unreachableBranch = handleEdgeCase()

When to Use

• AWS SDK wrapper functions (tested via integration tests)
• Unreachable error branches (TypeScript exhaustive checks)
• Environment-specific code paths

Enforcement

Automated

• ESLint (eslint-plugin-jsdoc): Requires JSDoc on exported functions, enforces hyphen format, forbids types in JSDoc
• ESLint (eslint-plugin-tsdoc): Validates TSDoc syntax
• ESLint (local-rules/spacing-conventions): Validates function spacing

Code Review Checklist

• [ ] No commented-out code
• [ ] No "removed" explanations
• [ ] No version history in comments
• [ ] TODOs have context/tickets
• [ ] Comments explain "why" not "what"
• [ ] Exported functions have JSDoc
• [ ] @param uses hyphen format

Related Patterns

• Code Formatting - dprint and // fmt: multiline / // dprint-ignore
• Git Workflow - Using Git as source of truth
• Naming Conventions - Self-documenting code through clear names
• Import Organization - Import documentation

---

Remember: The code shows WHAT, comments explain WHY, and Git shows HOW it evolved. Keep comments focused on the present implementation's reasoning, not its history.