dx-maintainability-reviewer

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