JSDoc Best Practices

Overview

This skill defines the JSDoc documentation standards for this project. The core principle is that documentation should explain "why", not just "what". Code already shows what it does—good documentation explains the reasoning, context, and non-obvious details that help developers understand and maintain the code.

Core Philosophy: Why Over What

The Problem with "What" Documentation

// Bad: Just restates the code
/**
 * Gets the user by ID
 * @param id - The ID
 * @returns The user
 */
function getUserById(id: string): User { ... }