Code Documentation

Code Documentation

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Create clear, comprehensive code documentation using language-specific standards like JSDoc, Python docstrings, JavaDoc, and inline comments.

When to Use

• Function and class documentation
• JSDoc for JavaScript/TypeScript
• Python docstrings
• JavaDoc for Java
• Inline code comments
• API documentation from code
• Type definitions
• Usage examples in code

Quick Start

Minimal working example:

/** * Calculates the total price including tax and discount. * * @param {number} basePrice - The base price before tax and discount * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%) * @param {number} [discount=0] - Optional discount amount * @returns {number} The final price after tax and discount * @throws {Error} If basePrice or taxRate is negative * * @example * const price = calculateTotalPrice(100, 0.08, 10); * console.log(price); // 98 * * @example * // Without discount * const price = calculateTotalPrice(100, 0.08); * console.log(price); // 108 */function calculateTotalPrice(basePrice, taxRate, discount = 0) {  if (basePrice < 0 || taxRate < 0) {    throw new Error("Price and tax rate must be non-negative");  }  return basePrice * (1 + taxRate) - discount;}
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

Best Practices

✅ DO

• Document public APIs thoroughly
• Include usage examples
• Document parameters and return values
• Specify thrown exceptions/errors
• Use language-specific standards (JSDoc, docstrings, etc.)
• Keep comments up-to-date
• Document "why" not "what"
• Include edge cases and gotchas
• Add links to related functions
• Document type definitions
• Use consistent formatting

❌ DON'T

• State the obvious in comments
• Leave commented-out code
• Write misleading comments
• Skip examples for complex functions
• Use vague parameter descriptions
• Forget to update docs when code changes
• Over-comment simple code