Code Documentation
Table of Contents
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:
| Guide | Contents |
|---|---|
| Function Documentation | Function Documentation |
| Class Documentation | Class Documentation |
| Type Definitions | Type Definitions |
| Function Documentation | Function Documentation |
| Class Documentation | Class Documentation |
| Module Documentation | Module Documentation |
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