Code Quality Review

Code Quality Review Methodology

Systematic patterns for reviewing code and providing constructive, actionable feedback that improves both code quality and developer skills.

When to Activate

• Reviewing pull requests or merge requests
• Assessing overall codebase quality
• Identifying and prioritizing technical debt
• Mentoring developers through code review
• Establishing code review standards for teams
• Auditing code for security or compliance

Review Dimensions

Every code review should evaluate these six dimensions:

1. Correctness

Does the code work as intended?

2. Design

Is the code well-structured?

3. Readability

Can others understand this code?

4. Security

Is the code secure?

5. Performance

Is the code efficient?

6. Testability

Can this code be tested?

Anti-Pattern Catalog

Common code smells and their remediation:

Method-Level Anti-Patterns

Class-Level Anti-Patterns

Architecture-Level Anti-Patterns

Review Prioritization

Focus review effort where it matters most:

Priority 1: Critical (Must Fix)

• Security vulnerabilities (injection, auth bypass)
• Data loss or corruption risks
• Breaking changes to public APIs
• Production stability risks

Priority 2: High (Should Fix)

• Logic errors affecting functionality
• Performance issues in hot paths
• Missing error handling for likely failures
• Violation of architectural principles

Priority 3: Medium (Consider Fixing)

• Code duplication
• Missing tests for new code
• Naming that reduces clarity
• Overly complex conditionals

Priority 4: Low (Nice to Have)

• Style inconsistencies
• Minor optimization opportunities
• Documentation improvements
• Refactoring suggestions

Constructive Feedback Patterns

The Feedback Formula

[Observation] + [Why it matters] + [Suggestion] + [Example if helpful]

Good Feedback Examples

# Instead of:
"This is wrong"

# Say:
"This query runs inside a loop (line 45), which could cause N+1
performance issues as the dataset grows. Consider using a batch
query before the loop:

```python
users = User.query.filter(User.id.in_(user_ids)).all()
user_map = {u.id: u for u in users}

"

```markdown
# Instead of:
"Use better names"

# Say:
"The variable `d` on line 23 would be clearer as `daysSinceLastLogin` -
it helps readers understand the business logic without tracing back
to the assignment."

Feedback Tone Guide

Positive Observations

Include what's done well:

"Nice use of the Strategy pattern here - it makes adding new
payment methods straightforward."

"Good error handling - the retry logic with exponential backoff
is exactly what we need for this flaky API."

"Clean separation of concerns between the validation and persistence logic."

Review Checklists

Quick Review Checklist (< 100 lines)

• Code compiles and tests pass
• Logic appears correct for stated purpose
• No obvious security issues
• Naming is clear
• No magic numbers or strings

Standard Review Checklist (100-500 lines)

All of the above, plus:

• Design follows project patterns
• Error handling is appropriate
• Tests cover new functionality
• No significant duplication
• Performance is reasonable

Deep Review Checklist (> 500 lines or critical)

All of the above, plus:

• Architecture aligns with system design
• Security implications considered
• Backward compatibility maintained
• Documentation updated
• Migration/rollback plan if needed

Review Workflow

Before Reviewing

1. Understand the context (ticket, discussion, requirements)
2. Check if CI passes (don't review failing code)
3. Estimate review complexity and allocate time

During Review

1. First pass: Understand the overall change
2. Second pass: Check correctness and design
3. Third pass: Look for edge cases and security
4. Document findings as you go

After Review

1. Summarize overall impression
2. Clearly indicate approval status
3. Distinguish blocking vs non-blocking feedback
4. Offer to discuss complex suggestions

Review Metrics

Track review effectiveness:

Anti-Patterns in Reviewing

Avoid these review behaviors:

References

• Review Dimension Details - Expanded criteria for each dimension
• Anti-Pattern Examples - Code examples of each anti-pattern