documentation-patterns

Apply when writing code documentation: JSDoc comments, README files, API documentation, and inline comments.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill provides standardized patterns and best practices for writing high-quality code documentation, including JSDoc, README files, and API documentation. It helps developers improve code maintainability and team collaboration by ensuring clear, consistent, and meaningful documentation across the codebase, following industry-standard guides like Write the Docs and JSDoc specifications.

Use Cases

  • Standardizing JSDoc comments for functions and modules to provide clear API references and improve IDE intellisense for development teams.
  • Creating structured and professional README files for projects to improve onboarding, usage clarity, and contribution workflows.
  • Implementing effective inline commenting strategies that explain the 'why' behind complex logic while eliminating redundant or obvious comments.
  • Managing technical debt and project tasks using standardized TODO, FIXME, and HACK tags linked to issue tracking systems.
  • Establishing consistent module and file headers to document the purpose, dependencies, and scope of specific code components.
namedocumentation-patterns
descriptionApply when writing code documentation: JSDoc comments, README files, API documentation, and inline comments.
version1.0.0
tokens~550
confidencehigh
- https//jsdoc.app/
last_validated2025-01-10
next_review2025-01-24
tags[documentation, jsdoc, readme, code-quality]

When to Use

Apply when writing code documentation: JSDoc comments, README files, API documentation, and inline comments.

Patterns

Pattern 1: Function Documentation (JSDoc)

// Source: https://jsdoc.app/
/**
 * Calculates the total price including tax and discounts.
 *
 * @param items - Array of cart items with price and quantity
 * @param taxRate - Tax rate as decimal (e.g., 0.1 for 10%)
 * @param discountCode - Optional discount code to apply
 * @returns Total price after tax and discounts
 * @throws {InvalidDiscountError} If discount code is invalid
 *
 * @example
 * const total = calculateTotal(
 *   [{ price: 100, quantity: 2 }],
 *   0.1,
 *   'SAVE10'
 * );
 * // Returns: 198 (200 - 10% discount + 10% tax)
 */
function calculateTotal(
  items: CartItem[],
  taxRate: number,
  discountCode?: string
): number {
  // ...
}

Pattern 2: README Structure

# Project Name

Brief description (1-2 sentences).

## Features
- Feature 1
- Feature 2

## Quick Start
\`\`\`bash
npm install
npm run dev
\`\`\`

## Usage
Basic usage example with code.

## API Reference
Link to detailed docs or brief overview.

## Configuration
Environment variables and options.

## Contributing
How to contribute.

## License
MIT

Pattern 3: When to Comment

// GOOD: Explain WHY, not WHAT
// Rate limit to prevent API abuse (max 100 req/min per user)
const rateLimiter = createRateLimiter({ max: 100, window: 60 });

// GOOD: Explain non-obvious behavior
// Sort descending because latest items should appear first
items.sort((a, b) => b.date - a.date);

// BAD: Obvious from code
// Increment counter by 1
counter++;

// BAD: Outdated comment (code changed, comment didn't)
// Check if user is admin  <-- comment says admin, code checks moderator
if (user.role === 'moderator') { }

Pattern 4: Module/File Header

/**
 * @fileoverview Authentication utilities for JWT token management.
 *
 * This module handles:
 * - Token generation and validation
 * - Refresh token rotation
 * - Session management
 *
 * @module auth/tokens
 * @see {@link https://jwt.io/introduction} for JWT spec
 */

Pattern 5: TODO Comments

// TODO: Implement caching - Issue #123
// FIXME: Race condition when multiple users update - urgent
// HACK: Workaround for library bug, remove after v2.0 upgrade
// NOTE: This relies on database trigger for audit log

// Include: action, context, reference (issue/ticket)
// TODO(john): Refactor after Q1 - JIRA-456

Anti-Patterns

  • No documentation - At minimum, public API needs docs
  • Obvious comments - i++ // increment i
  • Stale comments - Update when code changes
  • Comment instead of fix - Don't comment bad code, fix it

Verification Checklist

  • Public functions have JSDoc
  • README has quick start guide
  • Complex logic has WHY comments
  • No stale/outdated comments
  • TODOs have issue references