Key functions and complex logic have inline comments or JSDoc

Undocumented complex logic — scoring algorithms, multi-step data transformations, non-obvious conditionals — forces every developer who touches that code to reverse-engineer it from the implementation. ISO 25010 maintainability.analysability and reusability both degrade: exported functions without JSDoc cannot be safely consumed by callers who don't understand the contract. AI-generated business logic is especially prone to undocumented complexity because the model writes correct-but-opaque implementations that prioritize functionality over legibility.

Focus documentation effort on the code that earns it: non-trivial business logic, complex conditionals, and exported utility functions. Explain the why, not just the what:

/**
 * Computes the weighted category score for audit telemetry.
 * Skip/error results are excluded from both numerator and denominator
 * so they don't penalize the score as if they failed.
 */
export function computeCategoryScore(checks: Check[]): number | null {
  const applicable = checks.filter(c => c.result === 'pass' || c.result === 'fail')
  if (applicable.length === 0) return null
  // ...
}

TypeScript language servers surface JSDoc in IDE tooltips — document exported functions with @param and @returns and callers get inline help without reading the source.