Introduction
Code reviews are essential for maintaining code quality, sharing knowledge, and catching bugs before they reach production. Effective reviews balance thoroughness with speed, providing constructive feedback that improves code and developers.
Review Checklist
Code Quality
- Code follows project style guidelines and conventions
- Variable and function names are descriptive
- Complex logic is well-commented
- Functions are small and do one thing
- Duplication is eliminated (DRY principle)
- Error handling is comprehensive
- No hardcoded values (use constants/config)
Testing
- New functionality has unit tests
- Tests are meaningful and not trivial
- Edge cases are covered
- Tests are independent and repeatable
- Test names describe what they verify
Security
- No sensitive data in logs
- Input validation on all external inputs
- SQL injection prevention (use parameterized queries)
- Authentication and authorization checks
- No secrets in code (use environment variables)
Performance
- No unnecessary database queries (N+1 problem)
- Appropriate use of caching
- Efficient algorithms and data structures
- Async operations for I/O-bound tasks
Providing Feedback
Constructive Comments
# Good feedback examples
## Suggestion (not demand)
"Consider using a dictionary here for O(1) lookups instead of the current list iteration."
## Question (not accusation)
"What's the reasoning behind this approach? I'm wondering if there might be a simpler solution."
## Explanation (with rationale)
"This pattern could be confusing because X. Using Y would make it clearer because Z."
## Praise (when deserved)
"Nice solution! The error handling here is very thorough."
# Avoid
- "Change this" (imperative without explanation)
- "Wrong" (judgmental)
- "Why did you..." (accusatory)
- "This is bad" (unhelpful criticism)
Review Response Template
## Code Review: [PR Title]
### Summary
Reviewed by: @reviewer
Files changed: 5
Lines added: 200
Lines removed: 50
### What Works Well
- Clean separation of concerns
- Good test coverage
- Clear variable naming
### Suggestions
1. **Minor**: Consider extracting this logic into a helper function
2. **Minor**: The error message could be more specific
3. **Style**: Python variable names should use snake_case
### Concerns
**Blocking**: The database connection isn't closed in the error path. This could lead to connection leaks.
### Approve
✅ Approved with suggestions
Common Issues
Logic Errors
# Bug: Off-by-one error
for i in range(len(items) - 1): # Wrong: misses last item
process(items[i])
# Fixed
for i in range(len(items)):
process(items[i])
# Bug: Mutable default argument
def add_item(item, items=[]): # Wrong: shared across calls
items.append(item)
return items
# Fixed
def add_item(item, items=None):
if items is None:
items = []
items.append(item)
return items
Performance Issues
# Bug: N+1 query problem
users = db.query("SELECT * FROM users")
for user in users:
posts = db.query(
"SELECT * FROM posts WHERE user_id = ?", user.id
) # Query per user!
# Fixed: Eager loading or JOIN
users = db.query("""
SELECT u.*, p.*
FROM users u
LEFT JOIN posts p ON u.id = p.user_id
""")
Building Review Culture
For Authors
- Keep PRs small - Reviewable in 15-20 minutes
- Write clear descriptions - Explain what and why
- Self-review first - Catch obvious issues
- Respond to feedback - Don’t take it personally
- Ask questions - If you don’t understand
For Reviewers
- Review promptly - Within hours, not days
- Be specific - Explain issues clearly
- Be kind - Assume good intent
- Focus on important issues - Don’t nitpick style
- Approve when ready - Don’t block on minor issues
Conclusion
Effective code reviews improve code quality and team knowledge. Follow checklists for consistency, provide constructive feedback, and foster a positive culture. Reviews are about learning, not gatekeeping.
Resources
- Google’s Engineering Practices
- “Best Kept Secrets of Peer Code Review”
Comments