Code Readability Review

The Problem

Code is read ten times more than it is written. A function named proc() with nested ternaries, single-letter variables, and no comments forces every future reader to reverse-engineer intent from behavior. Developers spend 70% of their time reading code, yet code reviews focus almost entirely on correctness and ignore whether the code communicates clearly to the next human who touches it.

The Prompt

Review the following code for readability. Act as a team lead evaluating whether a junior developer could understand this code without asking questions.

LANGUAGE: [e.g., TypeScript, Python, Go, Java]

CODE:
[paste your code here]

Evaluate across these readability dimensions:

1. **Naming**
   - Are variables, functions, and classes named for their purpose (not abbreviations)?
   - Do boolean names read as questions (isActive, hasPermission, canEdit)?
   - Are collection names plural (users, not userList)?
   - Are constants UPPER_SNAKE_CASE and descriptive?

2. **Function Design**
   - Are functions under 20-30 lines?
   - Does each function do one thing (single responsibility)?
   - Are parameter lists short (max 3, use objects for more)?
   - Do return types clearly communicate success/failure?

3. **Cognitive Complexity**
   - How many levels of nesting (max 3 recommended)?
   - Are there nested ternaries or chained conditionals?
   - Can early returns replace deep nesting?
   - Is the control flow predictable (no goto/continue puzzles)?

4. **Comments & Documentation**
   - Do comments explain WHY, not WHAT?
   - Are magic numbers/strings extracted into named constants?
   - Are complex algorithms or business rules explained?
   - Are TODOs actionable (include ticket number or owner)?

5. **Structure & Formatting**
   - Is related code grouped together (cohesive sections)?
   - Are blank lines used to separate logical blocks?
   - Is the file a reasonable length (under 300 lines)?
   - Is dead code / commented-out code removed?

6. **Patterns & Consistency**
   - Is one pattern used for similar operations (not 3 ways to fetch data)?
   - Are error handling patterns consistent throughout?
   - Does the code follow the project's established conventions?

For each issue, provide:
- **Location**: File and line
- **Severity**: confusing (blocks understanding) / unclear / nitpick
- **Problem**: Why a reader would struggle
- **Fix**: Rewritten code with improved readability

Example Output

## Readability Review: 6 issues found

### Confusing: Cryptic Variable Names
Location: src/utils/process.ts:7
Code: `const r = await fn(d, o.p ? o.p : DEFAULT_P);`
Fix: `const result = await fetchReport(dateRange, options.pageSize ?? DEFAULT_PAGE_SIZE);`

### Confusing: Deeply Nested Conditionals
Location: src/services/auth.ts:23 — 5 levels of nesting
Code:
  if (user) {
    if (user.active) {
      if (user.verified) {
        if (hasPermission(user, resource)) {
          // actual logic
        }
      }
    }
  }
Fix (guard clauses):
  if (!user) return unauthorized();
  if (!user.active) return forbidden('Account inactive');
  if (!user.verified) return forbidden('Email not verified');
  if (!hasPermission(user, resource)) return forbidden('Insufficient permissions');
  // actual logic — flat and clear

### Unclear: Magic Number
Location: src/config.ts:15
Code: `setTimeout(retry, 3000)`
Fix: `const RETRY_DELAY_MS = 3000; setTimeout(retry, RETRY_DELAY_MS);`

When to Use

Run this on every pull request, especially code written under time pressure. Particularly valuable when onboarding new team members — readable code reduces ramp-up time from weeks to days. Use it as a teaching tool: pair junior developers’ code with this review to build naming and structuring habits early.

Pro Tips

• Read the code aloud — if you cannot naturally speak the function name and parameters as a sentence, the naming needs work. getUserByEmail(email) reads naturally; proc(d) does not.
• Ask for a refactored version — follow up with “Rewrite this entire file applying all suggestions, preserving exact functionality.”
• Measure cognitive complexity — ask “Calculate the cognitive complexity score (SonarQube methodology) for each function” to get a quantitative readability metric.