Practice : Code Reviews & Pull Requests

Purpose and Strategic Importance

Code Reviews and Pull Requests (PRs) are fundamental practices that ensure code quality, maintainability, and shared understanding. They provide opportunities for early feedback, collective ownership, and knowledge sharing across the team.

Beyond catching bugs, good reviews foster learning, improve consistency, and strengthen team alignment - contributing to a more resilient, inclusive, and high-performing engineering culture.

Description of the Practice

  • A developer submits a pull request with proposed code changes, typically to a shared branch.
  • Peers review the changes for correctness, clarity, performance, security, and design alignment.
  • Reviews are collaborative, not gatekeeping - the goal is improvement, not perfection.
  • Reviews may include inline comments, suggested changes, and approval or follow-up discussions.
  • Tools include GitHub, GitLab, Bitbucket, Azure Repos, and review bots for automation.

How to Practise It (Playbook)

1. Getting Started

  • Set up PR templates to guide authors on what to include (context, testing, related tickets).
  • Define team norms on what makes a PR ready for review (e.g. CI passing, self-reviewed).
  • Encourage small, focused PRs that are easier to review and reason about.
  • Use checklists to ensure completeness (e.g. tests, docs, accessibility).

2. Scaling and Maturing

  • Use review rotation or pairing to distribute review load.
  • Track review metrics (e.g. cycle time, comment density, time to merge) to improve flow.
  • Automate repetitive checks (e.g. linting, security scans, test coverage) with CI tools.
  • Evolve feedback from nitpicking to mentoring - coach on design, readability, and impact.
  • Celebrate constructive feedback and shared problem solving.

3. Team Behaviours to Encourage

  • Provide timely, respectful, and actionable feedback.
  • Ask clarifying questions rather than making assumptions.
  • Focus on the code, not the coder - separate people from their work.
  • Encourage authors to request feedback early and explain their thinking.

4. Watch Out For…

  • Long or unreviewed PRs blocking flow and feedback.
  • Overly large changesets that make review difficult or rushed.
  • Gatekeeping or harsh tone that discourages contribution.
  • Lack of documentation on decisions made during review.

5. Signals of Success

  • PRs are small, reviewed quickly, and merged confidently.
  • Teams share knowledge and improve code consistency.
  • Developers learn from each other through kind, clear feedback.
  • Codebase quality and maintainability steadily improve.
  • Review culture is supportive, inclusive, and valued by the team.