1. Write smaller pull requests
Instead of submitting huge PRs with hundreds or thousands of lines of code, aim to make smaller, focused changes.
- Why it helps: Small PRs are easier for reviewers to read, understand, and test. They reduce cognitive load and make it more likely that errors are caught before merging.
- Best practice: Try to keep PRs under ~200 lines of code and scoped to a single feature or bug fix.
2. Implement PR stacking
Break large changes into a series of smaller PRs, where each PR builds upon the previous one.
- Why it helps: Reviewers can focus on one logical change at a time instead of being overwhelmed. It also makes it easier to revert or modify parts of a feature if needed.
- Example: If adding a new authentication flow, one PR might create the data models, the next PR implements API endpoints, and the last PR handles the front-end integration.
3. Provide contextual details
Include thorough explanations in the PR description. Link to relevant tickets, code, or design documents, and add screenshots or diagrams if applicable.
- Why it helps: Reviewers don’t need to guess the intent of the code. Clear context reduces back-and-forth questions and speeds up the review process.
- Tip: A “What/Why/How” format works well:
- What: What is being changed?
- Why: Why is this change needed?
- How: How is this implemented?
4. Implement architectural safeguards
Design your codebase with modularity in mind and protect core components. Assign reviewers familiar with the impacted areas.
- Why it helps: Prevents breaking critical functionality and enforces consistency across the codebase.
- Example: If a change affects the authentication system, a reviewer familiar with security best practices should review it.
5. Encourage real-time collaboration
Promote active engagement during development, using live discussions, pair programming, or rapid prototyping.
- Why it helps: Immediate feedback reduces the number of iterations needed on PRs and improves code quality.
- Example: Two developers pair program on a tricky feature rather than submitting a large, error-prone PR later.
6. Loop in diverse expertise
Assign PR reviewers based on their specific domain knowledge, e.g., front-end, back-end, database, or security.
- Why it helps: Ensures changes are thoroughly reviewed by people who understand the potential pitfalls.
- Result: Fewer bugs slip through and team knowledge is shared effectively.
7. Actively balance team bandwidth
Keep track of how many PRs each team member is reviewing or working on. Avoid overloading developers.
- Why it helps: Reduces bottlenecks and keeps the team productive. PRs won’t sit unreviewed for long periods.
- Tip: Limit the number of open PRs per person and monitor review turnaround times.
8. Implement automation throughout the workflow
Use tools like GitHub Actions, Jenkins, or CI/CD pipelines to automatically check code. This includes linting, tests, formatting, and security checks.
- Why it helps: Automation catches errors early, enforces standards, and reduces the manual effort required for reviews.
- Example: A pull request fails the CI build if tests fail, preventing broken code from merging.
Seng Seang Leng
Web Developer