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.
Medium because undocumented complex logic multiplies the time required to safely modify or reuse it, but the immediate runtime behavior is unaffected.
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.
ID: code-maintainability.documentation.function-comments
Severity: medium
What to look for: Examine the 10-15 most substantial non-trivial functions or methods in the codebase (focus on business logic, data transformations, algorithm-like code, and complex conditionals — not simple getters or straightforward CRUD). Check for:
/** ... */) on exported functions explaining parameters and return valuesDo not penalize simple, self-explanatory functions for lacking comments. The question is whether the genuinely complex parts have any documentation.
Pass criteria: Count all non-trivial functions (over 10 lines of logic, or containing complex conditionals/algorithms) and classify each as documented or undocumented. At least 60% of non-trivial functions have at least a brief comment explaining their purpose or non-obvious behavior. Report the ratio: "X of Y non-trivial functions are documented."
Fail criteria: The majority of complex functions (over 5 lines of non-trivial logic) have no comments whatsoever. Or the codebase has complex business logic (scoring, calculations, multi-step processes) with zero documentation.
Skip (N/A) when: The project has no non-trivial logic — only simple CRUD operations and UI rendering with no complex transformations. Signal: all functions are <5 lines and have self-explanatory names.
Detail on fail: "Complex business logic in lib/scoring.ts has no comments — 80-line scoring function with multiple weighted calculations and edge cases is undocumented." or "10 exported utility functions in lib/ have no JSDoc — parameter types and return values must be inferred from TypeScript types alone."
Remediation: Documentation doesn't need to be exhaustive. A one-line comment on a complex function pays dividends for years. Focus on explaining 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
// ...
}
For exported functions, add JSDoc with @param and @returns — TypeScript language servers will surface this in IDE tooltips, helping future developers without them having to read the source.