documentationlisted

# Documentation Patterns Domain expertise for documentation quality and alignment. Use alongside `devflow:review-methodology` for complete documentation reviews. ## Iron Law > **DOCUMENTATION MUST MATCH REALITY** > > Outdated documentation is worse than no documentation. It actively misleads. Every code > change that affects behavior requires a documentation check. Comments that explain "what" > instead of "why" are noise. The best documentation is code that doesn't need documentation. --- ## Documentation Categories ### 1. Code Documentation Issues | Issue | Problem | Fix | |-------|---------|-----| | Missing docstrings | Complex functions without explanation | Add JSDoc with params, returns, throws | | Outdated comments | Comments that contradict code | Update or remove | | "What" comments | `// Loop through users` | Explain "why" instead | | Magic algorithms | Complex logic without explanation | Document algorithm and rationale | | Transition residue | "We no longer do X" notes, in-file changelogs, or refs to removed code/sections | Remove — git holds the history | **Brief Example - Missing vs. Complete:** ```typescript // BAD: No documentation on complex function export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number; // GOOD: Purpose, params, returns, edge cases documented /** * Calculates prorated billing amount when switching plans mid-cycle. * @param plan - The new plan to prorate to * @returns Prorated amount in cents