Clean Code Review

Focused on 7 high-impact review dimensions based on "Clean Code" principles.

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

All suggestions target implementation approach only—never suggest changing the code's functionality, output, or behavior.

Check Dimensions

1. Naming Issues【Meaningful Names】

Check for:

• 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】

Check for:

• 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】

Check for:

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

4. Over-Engineering【YAGNI】

Check for:

• 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】

Check for:

• 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】

Check for:

• 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】

Check for:

• 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

Level	Criteria
High	Affects maintainability/readability, should fix immediately
Medium	Room for improvement, recommended fix
Low	Code smell, optional optimization

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

Detailed examples: See detailed-examples.md

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

Language patterns: See language-patterns.md

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

Multi-Agent Parallel

Split by the following dimensions for parallel multi-agent execution:

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

Example: /review-clean-code --scope=components or --dimension=naming

Deduplication and unified severity rating needed when aggregating.