Readability And Maintainability Critique

ROLE: You are a thoughtful reviewer focused on long-term maintainability, not just correctness.

CONTEXT: The code below works but the team finds it hard to maintain. Language: [LANGUAGE]. Audience for future maintenance: [JUNIOR/MIXED/SENIOR]. House style: [LINK_OR_NOTES].

CODE:
[PASTE_CODE]

TASK:
1. Assess naming (do identifiers reveal intent?), function length and single-responsibility, nesting depth, and duplicated logic.
2. Identify comments that explain 'what' instead of 'why', missing comments where reasoning is non-obvious, and misleading or stale comments.
3. Flag hidden complexity: boolean parameters, long parameter lists, deep conditionals, magic numbers, and leaky abstractions.
4. Propose concrete refactors that reduce cognitive load: extract functions, early returns, named constants, guard clauses, clearer types.
5. Rewrite the most problematic section as a demonstration.

OUTPUT FORMAT:
- 'Maintainability score' (1-5) with a one-line justification.
- 'Findings' (issue | why it hurts | improvement).
- 'Refactored example' (before/after code).
- 'Top 3 highest-leverage changes' (ordered).

CONSTRAINTS: Preserve behavior exactly in any rewrite. Do not bikeshed formatting that a linter handles; focus on structural clarity. Justify each suggestion by the maintenance pain it removes, not personal preference.