This project is a guide and template for perspective-based code reviews, to improve review quality and help team members develop expertise in identifying different types of issues.
Instead of trying to catch everything in one review, reviewers explicitly choose one or more perspectives to review from. Each perspective focuses on a specific type of concern with targeted questions and patterns to look for.
Each perspective guide is split into stack-agnostic principles followed by a Django/Celery Examples section. The principles transfer to other stacks; replace the examples section with whatever fits your codebase.
For the rationale, related research, and trade-offs, see perspective-based-code-reviews.pdf.
-
- Logic correctness, edge cases, error handling
- Null handling, boundary conditions
- Scope: Does it work correctly?
-
- Code clarity, readability, structure
- Patterns, naming, technical debt
- Scope: Can we maintain this in 6 months? Years?
-
- Test quality and logical coverage
- Edge cases and error paths
- Scope: Is it testable and tested properly?
-
- Migration safety, backward compatibility
- Database constraints, data integrity
- Scope: Are schema changes safe?
-
- Query performance, N+1 problems, complexity
- Caching, async patterns, observability
- Scope: Will it scale?
-
- Authentication, authorization
- Data exposure, input validation
- Scope: Is it secure?
These six are a starting set, not a fixed framework. Teams can split, merge, or replace perspectives to fit their stack and risk profile — e.g., a frontend team might add an Accessibility perspective; a data team might split Data and Migrations from Pipeline Correctness.
- Choose 1-2 perspectives based on the PR type and your expertise
- Open the perspective card - keep it as reference while reviewing
- Scan "Red Flags" section for patterns to watch for
- Review the PR looking specifically for those patterns
- Declare your perspective in your review comments
Not prescriptive — these are starting points. Reviewers should still use judgement and pick what fits the change.
| PR shape | Likely perspectives |
|---|---|
| New API endpoint | Correctness, Security |
| Auth, permissions, tenant boundary change | Security (+ Correctness) |
| Database migration / schema change | Data and Migrations (+ Performance) |
| Query, list endpoint, or background job | Performance and Scalability (+ Correctness) |
| Refactor with no behavior change | Maintainability (+ Testing) |
| New feature or model | Correctness, Testing (+ one of the others) |
| Bug fix | Correctness, Testing |
Use this format to declare your perspective and provide feedback:
**Security CR**:
Missing organization boundary check. A user could access submissions from other orgs.
Suggestion: Add organization filter to the queryset.
**Security LGTM**:
Good permission checks - validates authentication, organization, and role.
**Security QUESTION**:
Should the bulk endpoint also enforce the per-row organization filter, or is the
queryset already scoped upstream?
**Security N/A**:
These changes have no impact on security or access.**[Perspective] LGTM**- Looks good from this perspective**[Perspective] CR**- Change requested from this perspective**[Perspective] QUESTION**- Need clarification (not blocking)**[Perspective] N/A**- This perspective does not really apply
These are bold-text conventions, not GitHub labels or check-runs — easy to write, but not machine-readable. If you later want to query "which PRs got a Security review", consider promoting them to GitHub labels or required check-runs.
- Makes gaps visible - We can see which perspectives were covered
- Focus - Clear guidance on what to look for
- Specificity - Different perspectives catch different issues
- Reduces overwhelm - Don't have to catch everything in one review
Key Principle: It's OK to miss things, especially from outside of the chosen perspective. The aim is to focus on a narrower aspect to improve quality. The main question to answer for any review is still "Will this PR make the product better than before?"
- Don't overthink it - Pick a perspective, open the card, review
- Be explicit - Declare your perspective in comments
- It's a learning tool - Use this to build expertise, not just find bugs
- Give feedback - If a perspective card needs improvement, improve them!
Background:
Perspective Cards:
CC BY 4.0 — share and adapt with attribution.