Clean Code Review

Review Workflow

Review Progress:
- [ ] 1. Scan codebase: identify files to review
- [ ] 2. Check each dimension (naming, functions, DRY, YAGNI, magic numbers, clarity, conventions)
- [ ] 3. Rate severity (High/Medium/Low) for each issue
- [ ] 4. Generate report sorted by severity

Core Principle: Preserve Functionality

Check Dimensions

1. Naming Issues【Meaningful Names】

• Meaningless names like

  data1

  ,

  temp

  ,

  result

  ,

  info

  ,

  obj

• Inconsistent naming for same concepts (

  get

  /

  fetch

  /

  retrieve

  mixed)

// ❌ 
const d = new Date();
const data1 = fetchUser();

// ✅ 
const currentDate = new Date();
const userProfile = fetchUser();

2. Function Issues【Small Functions + SRP】

• Functions exceeding 100 lines
• More than 3 parameters
• Functions doing multiple things

// ❌ 7 parameters
function processOrder(user, items, address, payment, discount, coupon, notes)

// ✅ Use parameter object
interface OrderParams { user: User; items: Item[]; shipping: Address; payment: Payment }
function processOrder(params: OrderParams)

3. Duplication Issues【DRY】

• Similar if-else structures
• Similar data transformation/error handling logic
• Copy-paste traces

4. Over-Engineering【YAGNI】

• if (config.legacyMode)

  branches that are never true
• Interfaces with only one implementation
• Useless try-catch or if-else

// ❌ YAGNI violation: unused compatibility code
if (config.legacyMode) {
  // 100 lines of compatibility code
}

5. Magic Numbers【Avoid Hardcoding】

• Bare numbers without explanation
• Hardcoded strings

// ❌ 
if (retryCount > 3) // What is 3?
setTimeout(fn, 86400000) // How long is this?

// ✅ 
const MAX_RETRY_COUNT = 3;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

6. Structural Clarity【Readability First】

• Nested ternary operators
• Overly compact one-liners
• Deep conditional nesting (> 3 levels)

// ❌ Nested ternary
const status = a ? (b ? 'x' : 'y') : (c ? 'z' : 'w');

// ✅ Use switch or if/else
function getStatus(a, b, c) {
  if (a) return b ? 'x' : 'y';
  return c ? 'z' : 'w';
}

7. Project Conventions【Consistency】

• Mixed import order (external libs vs internal modules)
• Inconsistent function declaration styles
• Mixed naming conventions (camelCase vs snake_case)

// ❌ Inconsistent style
import { api } from './api'
import axios from 'axios'  // External lib should come first
const handle_click = () => { ... }  // Mixed naming style

// ✅ Unified style
import axios from 'axios'
import { api } from './api'
function handleClick(): void { ... }

[!TIP] Project conventions should refer to

CLAUDE.md

,

AGENTS.md

, or project-defined coding standards.

Severity Levels

Output Format

### [Issue Type]: [Brief Description]

- **Principle**: [Clean Code principle]
- **Location**: `file:line`
- **Severity**: High/Medium/Low
- **Issue**: [Specific description]
- **Suggestion**: [Fix direction]

Artifacts (Pipeline Mode)

• Output:

  clean-code-review.md

  (human-readable report)
• Output:

  clean-code-review.json

  (structured issue list for aggregation/deduplication/statistics)

References

• Complete cases for each dimension (naming, functions, DRY, YAGNI, magic numbers)

• TypeScript/JavaScript common issues
• Python common issues
• Go common issues

Multi-Agent Parallel

1. By check dimension - One agent per dimension (7 total)
2. By module/directory - One agent per module
3. By language - One agent each for TypeScript, Python, Go
4. By file type - Components, hooks, utilities, type definitions

/review-clean-code --scope=components

--dimension=naming