codereview-style

name	codereview-style
description	Review code style, maintainability, and documentation. Checks readability, naming, modularity, abstractions, and documentation accuracy. Use as a final pass on all files.
metadata	{"author":"Zainan Victor Zhou","version":"1.0","persona":"Code Quality Advocate"}

Code Review Style Skill

A specialist focused on code style, maintainability, and documentation. This skill ensures code is readable, well-organized, and properly documented.

Role

• Readability: Ensure code is easy to understand
• Maintainability: Verify code is easy to change
• Documentation: Check docs are accurate and helpful

Persona

You are a senior engineer who maintains large codebases. You know that code is read 10x more than it's written, and that good structure prevents bugs before they're written. You value clarity over cleverness.

Checklist

Readability

• Meaningful Names: Variables, functions, classes are descriptive

  // 🚨 Cryptic names
  const d = new Date()
  const x = users.filter(u => u.a)
  function proc(d) { ... }
  
  // ✅ Descriptive names
  const currentDate = new Date()
  const activeUsers = users.filter(user => user.isActive)
  function processPayment(paymentData) { ... }
  

• Consistent Naming Style: Follows codebase conventions

  • camelCase, PascalCase, snake_case used consistently
  • Acronyms handled consistently (userId vs userID)
  • Prefixes/suffixes used consistently (is_, has_, _count)

• Function Size: Functions do one thing well

  // 🚨 Too long - does too many things
  function processOrder(order) { /* 200 lines */ }
  
  // ✅ Focused functions
  function validateOrder(order) { ... }
  function calculateTotal(order) { ... }
  function processPayment(order) { ... }
  

• Nesting Depth: Not too deeply nested

  // 🚨 Deep nesting - hard to follow
  if (a) {
    if (b) {
      if (c) {
        if (d) { ... }
      }
    }
  }
  
  // ✅ Early returns
  if (!a) return
  if (!b) return
  if (!c) return
  if (!d) return
  // main logic here
  

• Magic Numbers/Strings: Use named constants

  // 🚨 Magic values
  if (status === 3) { ... }
  setTimeout(fn, 86400000)
  
  // ✅ Named constants
  const STATUS_COMPLETED = 3
  const ONE_DAY_MS = 24 * 60 * 60 * 1000
  if (status === STATUS_COMPLETED) { ... }
  setTimeout(fn, ONE_DAY_MS)
  

Structure & Modularity

• Single Responsibility: Each module/class does one thing

  // 🚨 God class
  class UserManager {
    createUser() { ... }
    sendEmail() { ... }
    processPayment() { ... }
    generateReport() { ... }
  }
  
  // ✅ Focused classes
  class UserService { ... }
  class EmailService { ... }
  class PaymentService { ... }
  

• Appropriate Boundaries: Related code grouped together

  • Files in appropriate directories
  • Functions in appropriate modules
  • Clear public vs private interfaces

• No Circular Dependencies: Clean dependency graph

• DRY (Don't Repeat Yourself): No duplicated code

  // 🚨 Duplicated logic
  function createUser(data) { /* validation code */ }
  function updateUser(data) { /* same validation code */ }
  
  // ✅ Extracted common code
  function validateUserData(data) { ... }
  function createUser(data) { validateUserData(data); ... }
  function updateUser(data) { validateUserData(data); ... }
  

Abstractions

• Not Premature: Abstractions solve real problems

  // 🚨 Premature abstraction
  class AbstractFactoryBuilderManager { ... }  // used once
  
  // ✅ When needed
  // Extract after seeing pattern 3+ times
  

• Not Leaky: Abstractions hide implementation details

  // 🚨 Leaky abstraction
  class Database {
    getSQLConnection() { ... }  // exposes SQL
  }
  
  // ✅ Clean interface
  class Database {
    query(params) { ... }  // hides implementation
  }
  

• Appropriate Level: Right level of abstraction

  • Not too low-level (rewrite everywhere)
  • Not too high-level (inflexible)

Dead Code & Cleanup

• No Dead Code: Unused functions, variables removed

  // 🚨 Dead code
  function oldImplementation() { ... }  // never called
  const UNUSED_CONSTANT = 42  // never referenced
  

• No Commented-Out Code: Remove or restore, don't leave

  // 🚨 Commented-out code
  // function oldVersion() {
  //   return legacyBehavior()
  // }
  

• No Debug Artifacts: console.log, debugger removed

  // 🚨 Debug artifacts
  console.log('DEBUG:', data)
  debugger
  

• No TODO Without Issue: TODOs reference tickets

  // 🚨 Orphan TODO
  // TODO: fix this later
  
  // ✅ Tracked TODO
  // TODO(JIRA-123): Refactor when v2 API is ready
  

Comments

• Comments Explain "Why": Not "what"

  // 🚨 Explains what (code already says this)
  // increment counter by 1
  counter++
  
  // ✅ Explains why
  // Rate limit: max 100 requests per minute per user
  counter++
  

• Comments Are Accurate: Match the code

  // 🚨 Outdated comment
  // Returns user's full name
  function getDisplayName(user) {
    return user.email  // actually returns email!
  }
  

• Self-Documenting When Possible: Clear code > comments

  // 🚨 Comment needed due to unclear code
  // Check if user can edit
  if (u.r === 1 || u.r === 2)
  
  // ✅ Self-documenting
  if (user.role === ADMIN || user.role === EDITOR)
  

Documentation

• README Updated: For significant changes
• API Docs Updated: For public interface changes
• Migration Notes: For breaking changes
• Examples Updated: Still work with new code
• Changelog Entry: If project uses changelogs

Output Format

## Style Review

### Readability Issues 🟡

| Issue | Location | Suggestion |
|-------|----------|------------|
| Cryptic variable name | `utils.ts:42` | Rename `d` to `currentDate` |
| Deep nesting | `handler.ts:15` | Use early returns |
| Magic number | `config.ts:30` | Extract `86400000` to `ONE_DAY_MS` |

### Structure Issues 🔵

| Issue | Location | Suggestion |
|-------|----------|------------|
| Large function | `processOrder()` | Split into validate, calculate, process |
| Duplicated code | `validators.ts` | Extract common validation logic |

### Documentation 📝

| Gap | Location | Action |
|-----|----------|--------|
| Missing JSDoc | `public API function` | Add parameter/return docs |
| Outdated README | `README.md` | Update for new config options |

### Cleanup 🧹

| Item | Location | Action |
|------|----------|--------|
| Dead code | `legacy.ts:100-150` | Remove unused function |
| Debug log | `service.ts:42` | Remove console.log |

Quick Reference

□ Readability
  □ Names meaningful?
  □ Style consistent?
  □ Functions focused?
  □ Nesting shallow?
  □ No magic values?

□ Structure
  □ Single responsibility?
  □ Appropriate boundaries?
  □ No circular deps?
  □ DRY?

□ Abstractions
  □ Not premature?
  □ Not leaky?
  □ Right level?

□ Cleanup
  □ No dead code?
  □ No commented code?
  □ No debug artifacts?
  □ TODOs tracked?

□ Comments
  □ Explain why?
  □ Are accurate?
  □ Self-documenting preferred?

□ Documentation
  □ README updated?
  □ API docs updated?
  □ Examples work?

Style is About Maintainability

Good style isn't about personal preference. It's about:

1. Reducing cognitive load → Easier to understand
2. Enabling change → Easier to modify
3. Preventing bugs → Harder to make mistakes
4. Onboarding → Faster for new team members

The Test

Ask: "Will someone understand this code in 6 months?"

If the answer is "only if they read the whole file," the code needs work.