DX & Maintainability Reviewer

Evaluate how easy it is for a new engineer to understand, modify, and work in this codebase. Focus on cognitive load, clarity, and sustainable development practices.

Core Principle

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." — Martin Fowler

When to Use

• Onboarding new team members
• Reviewing code quality after feature work
• Assessing technical debt before sprints
• Evaluating codebases during due diligence
• Planning refactoring efforts
• Improving team velocity

Review Workflow

Step 1: First Impressions (New Engineer Simulation)

Approach the codebase as a new engineer would:

Questions a new engineer asks:
1. What does this project do? (README)
2. How do I run it locally? (Setup docs)
3. Where is the code for X? (Project structure)
4. How do I make a change? (Contribution guide)
5. What patterns should I follow? (Conventions)
6. Who do I ask for help? (Team/ownership)

Time yourself:

• Can find entry point in < 2 minutes?
• Can run locally in < 15 minutes?
• Can understand main flow in < 1 hour?

Step 2: Structural Analysis

# Project structure overview
tree -L 3 -d --noreport

# File count by type
find . -type f -name "*.ts" | wc -l

# Largest files (complexity indicators)
find . -name "*.ts" -exec wc -l {} \; | sort -rn | head -20

# Most changed files (hotspots)
git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20

Step 3: Code Complexity Scan

# Longest files first — the top of this list is the hotspot set
find . -name "*.ts" -exec wc -l {} + | sort -rn | head -20

# Long functions (rough heuristic)
grep -rn "function\|async\|=>" --include="*.ts" -A 100 | head -200

# Deep nesting (many closing braces together)
grep -rn "}}}\|}}}}" --include="*.ts"

# TODO/FIXME/HACK count
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" | wc -l

Step 4: Execute Checklist

The complete checklist and the code-smell catalogue are inline in this file — there are no companion files. (Both were cited here for months and never shipped.)

Output Format

A) Developer Experience Score

┌─────────────────────────────────────────────────────────────┐
│                  DX SCORECARD                                │
├─────────────────────────────────────────────────────────────┤
│ Category              │ Score │ Notes                       │
├───────────────────────┼───────┼─────────────────────────────┤
│ Setup & Onboarding    │ [/10] │ [brief note]                │
│ Code Organization     │ [/10] │ [brief note]                │
│ Naming & Readability  │ [/10] │ [brief note]                │
│ Documentation         │ [/10] │ [brief note]                │
│ Testing               │ [/10] │ [brief note]                │
│ Error Messages        │ [/10] │ [brief note]                │
│ Tooling & Automation  │ [/10] │ [brief note]                │
├───────────────────────┼───────┼─────────────────────────────┤
│ OVERALL DX SCORE      │ [/70] │ [EXCELLENT/GOOD/FAIR/POOR]  │
└─────────────────────────────────────────────────────────────┘

B) Cognitive Load Hotspots

Areas that require excessive mental effort to understand:

### :red_circle: HIGH COGNITIVE LOAD: [filename]

**Location:** `path/to/file.ts`
**Lines:** [count]
**Complexity indicators:**
- [indicator 1]
- [indicator 2]

**Why it's hard to understand:**
[Explanation]

**Suggested improvement:**
[Concrete suggestion]

Cognitive load causes:

C) Naming & Structure Problems

### NAMING: [Problem Title]

**Location:** `path/to/file.ts:123`
**Current:** `[current name]`
**Problem:** [Why it's confusing]
**Suggested:** `[better name]`

### STRUCTURE: [Problem Title]

**Location:** `path/to/directory/`
**Problem:** [What's wrong with structure]
**Suggested:** [Better organization]

D) Missing Documentation

┌─────────────────────────────────────────────────────────────┐
│               DOCUMENTATION GAPS                             │
├─────────────────────────────────────────────────────────────┤
│ Document                    │ Status        │ Priority      │
├─────────────────────────────┼───────────────┼───────────────┤
│ README.md                   │ ⚠️ Incomplete │ HIGH          │
│ CONTRIBUTING.md             │ ❌ Missing    │ MEDIUM        │
│ Architecture overview       │ ❌ Missing    │ HIGH          │
│ API documentation           │ ✅ Present    │ -             │
│ Setup guide                 │ ⚠️ Outdated   │ HIGH          │
│ Deployment runbook          │ ❌ Missing    │ CRITICAL      │
│ Incident runbook            │ ❌ Missing    │ HIGH          │
│ ADR (decisions)             │ ❌ Missing    │ MEDIUM        │
└─────────────────────────────┴───────────────┴───────────────┘

For each missing critical document:

### MISSING: [Document Name]

**Why needed:** [Impact of not having it]
**Should contain:**
- [Section 1]
- [Section 2]
- [Section 3]

**Template:** [Link to template if available]

E) Refactor Opportunities

┌─────────────────────────────────────────────────────────────┐
│              REFACTOR OPPORTUNITIES                          │
├──────────────┬──────────────┬────────────────────────────────┤
│ Priority     │ Effort       │ Opportunity                    │
├──────────────┼──────────────┼────────────────────────────────┤
│ HIGH         │ Medium       │ Extract OrderService from...   │
│ HIGH         │ Low          │ Rename confusing variables...  │
│ MEDIUM       │ High         │ Split monolithic file...       │
│ MEDIUM       │ Medium       │ Add error handling pattern...  │
│ LOW          │ Low          │ Remove dead code in...         │
└──────────────┴──────────────┴────────────────────────────────┘

For high-priority refactors:

### REFACTOR: [Title]

**Location:** `path/to/file.ts`
**Current state:** [What it looks like now]
**Problem:** [Why this needs to change]
**Proposed change:** [What to do]
**Effort:** [Low/Medium/High]
**Risk:** [Low/Medium/High]
**Dependencies:** [What else might need to change]

F) Quick Wins

Changes that significantly improve DX with minimal effort:

QUICK WINS (< 1 hour each):
1. [ ] Add missing npm scripts for common tasks
2. [ ] Add .env.example with all required variables
3. [ ] Fix misleading error message in [file]
4. [ ] Add JSDoc to exported function [name]
5. [ ] Delete unused file [path]

G) Summary & Recommendations

┌─────────────────────────────────────────────────────────────┐
│                    SUMMARY                                   │
├─────────────────────────────────────────────────────────────┤
│ Overall DX:          [EXCELLENT/GOOD/FAIR/POOR]             │
│ Onboarding time:     [estimate for new engineer]            │
│ Cognitive hotspots:  [count]                                │
│ Missing docs:        [count]                                │
│ Refactor debt:       [estimate: days/weeks]                 │
├─────────────────────────────────────────────────────────────┤
│ TOP 3 PRIORITIES:                                           │
│ 1. [Most impactful improvement]                             │
│ 2. [Second priority]                                        │
│ 3. [Third priority]                                         │
└─────────────────────────────────────────────────────────────┘

Quick Commands

# Find largest files
find . -name "*.ts" -exec wc -l {} \; | sort -rn | head -10

# Find most complex files (by cyclomatic complexity proxy)
grep -rn "if\|else\|switch\|case\|for\|while\|catch\|&&\|||" --include="*.ts" -c | sort -t: -k2 -rn | head -10

# Find files with most imports (coupling)
grep -rn "^import" --include="*.ts" -c | sort -t: -k2 -rn | head -10

# Find TODO/FIXME
grep -rn "TODO\|FIXME" --include="*.ts" --include="*.tsx"

# Find commented-out code
grep -rn "^[[:space:]]*//.*function\|^[[:space:]]*//.*const\|^[[:space:]]*//.*if" --include="*.ts"

# Find magic numbers
grep -rn "[^a-zA-Z0-9][0-9][0-9][0-9][0-9]*[^a-zA-Z0-9]" --include="*.ts" | grep -v "test\|spec"

# Find any/unknown types (TypeScript)
grep -rn ": any\|as any\|<any>" --include="*.ts"

# Check for consistent naming
grep -rn "camelCase\|snake_case\|PascalCase" --include="*.ts" | head -20

Resources