Pull requests are a crucial part of the collaborative development workflow on GitHub. They allow team members to review and discuss changes before integrating them into the main codebase. Properly reviewing pull requests is essential for maintaining code quality, finding bugs, sharing knowledge, and aligning with coding standards. However, reviewing pull requests can also be challenging if not done thoughtfully. In this comprehensive guide, we’ll cover best practices and effective strategies for reviewing pull requests so you can collaborate smoothly and ship better code.

Introduction

For developers using GitHub, reviewing pull requests from team members is a regular part of the workflow. When a developer makes changes to the code on a separate branch or fork, they can submit a pull request to propose integrating those changes into the main repository. The pull request opens up a space for discussion, review and iteration before the changes get merged.

Reviewing incoming pull requests is important for several reasons:

• Catch bugs early: Reviewing code changes line-by-line helps identify potential bugs, edge cases or unintended behavior before changes impact the whole codebase.
• Maintain standards: Reviews help ensure all code going into the main branch adheres to style guides, architecture rules, and other standards.
• Spread knowledge: Peer code reviews allow team members to learn about areas of the codebase they don’t work on regularly.
• Improve code: Reviewers can suggest better approaches, optimizations and simplifications to improve the overall code quality.

However, reviewing pull requests can also be challenging:

• Time investment: Thorough reviews take time – going line-by-line through all changes. Reviewers need to balance thoroughness with speed.
• Interpersonal dynamics: Reviews critique someone’s creative work and can lead to negative emotions if not handled with care.
• Lack of standards: Without clear standards, reviews may vary drastically between team members.

In this guide, we’ll cover proven practices and strategies to help reviewers provide timely, high-quality feedback that improves code and collaboration.

Effective Mindsets for Reviewing Pull Requests

Approaching pull request reviews with the right mindset sets the stage for constructive collaboration. Keep these principles in mind:

Provide Timely, Constructive Feedback

Reviewing pull requests quickly shows respect for the author’s time investment and avoids inefficient context switching if they have moved on to other tasks. However, hasty reviews can miss important details. Strive to start reviewing pull requests within a few hours, but spend enough time to thoroughly understand the changes.

When providing feedback, give specific, positive suggestions focused on improving the code rather than criticisms of the author. Saying “this code is poorly written” doesn’t help. Saying “let’s use a HashMap here for better time complexity” gives the author clear direction.

Use language focused on the code, not the individual. Say “this code could be improved by…” instead of “you should change this code.”

Prioritize the Code Over the Individual

It’s natural to get defensive when someone critiques your work. As a reviewer, put code quality and the health of the overall project above any individual ego. The goal is not to prove you know more than the author, but to produce the best end result.

If disagreements about approach arise, use objective technical reasoning focused on benefits to the project rather than feelings or opinions. Discuss respectfully and keep an open mind to reach the optimal solution.

Maintain a Learning Mindset

No one writes perfect code all the time. Assume the author has positive intent and remember you can learn from every review. Ask clarifying questions rather than assumptions. If you see code that could be improved, view it as an opportunity to spread knowledge, not just correct mistakes.

Actionable Strategies for Reviewing Pull Requests

Beyond mindset, here are some tactical techniques for performing effective pull request reviews:

Clarify Exact Changes Needed

Be extremely clear, specific and direct in review comments. Vague, ambiguous language leads to confusion and delays.

• Specify the exact line number when referring to a section of code.
• Quote the relevant code snippet or error message verbatim.
• Use precise language like “Pass userId as a parameter here” rather than “You need to fix the user logic here.”

If suggesting a code change, provide the exact code to add or replace rather than just describing it. This removes all ambiguity.

Perform Thorough Testing

Don’t just assume the author’s code works as intended. Reviewers should always independently verify changes.

• Check out the branch locally and test functionality manually. Look for bugs and edge cases.
• Run existing tests locally to ensure the changes don’t break anything.
• If available, run static analysis tools to catch errors like linting.

Thorough testing catches issues before they impact customers and helps authors learn what they may have overlooked.

Reinforce Best Practices

Leverage the pull request review to reinforce team best practices around things like:

• Small, focused pull requests: Encourage splitting changes into multiple small PRs.
• Test coverage: Require authors to include unit tests with code changes.
• Templates: Use PR description templates to standardize change info.
• Automation: Implement CI checks to run tests automatically on PRs.

Reinforcing best practices prevents technical debt and mistakes from accumulating over time.

What to Review in a Pull Request

Now that we’ve covered overall mindsets and strategies, let’s look at the specific things reviewers should examine in a pull request:

The Code Itself

The core of any review is examining the code diffs and changed files line-by-line.

• Understand what the code change aims to accomplish.
• Check for syntax issues, bugs, unclear logic, or code that could be simplified.
• Verify consistent style and conventions are followed.
• Leave comments on specific lines noting issues or questions.
• Suggest improvements to code quality or performance.

Looking at the code itself allows you to ensure correctness and maintain standards.

Tests

Verify the author included updated or new tests relevant to the change:

• Check unit tests for new functions and modules.
• Confirm existing integration tests still pass.
• Look for opportunities to add more test coverage.

Thorough testing prevents regressions and catches overlooked edge cases.

Documentation

Ensure any API changes are reflected in documentation:

• Public API docs should note added, removed, or changed methods.
• Check for incorrect comments and outdated info.
• See if complex sections could use more comments.

Clear documentation allows future developers to understand the code.

Satellite Files

Scan other files like configurations that may be impacted:

• Review changes to config files, build scripts, CI pipelines, etc.
• Verify the changelog summary matches the pull request.
• Check for new dependencies added to package.json.

Keeping satellite files in sync prevents subtle bugs down the line.

By methodically reviewing each of these areas, you can feel confident in approving or requesting changes to the pull request.

Best Practices for Requesting Changes

If issues are found during review, you’ll need to request changes before the pull request can be approved and merged. Here are some tips for making effective change requests:

• Be polite. Thank the author for their effort and reiterate you are trying to improve the overall code.
• Prioritize requests. Call out the biggest issues that must be fixed first.
• Provide specific guidance. Link to docs, reference other code, or show example fixes.
• Ask clarifying questions if you don’t understand something.
• Request tests for changed functionality.
• If needed, recommend trying a different design approach.
• Request small iterations. Don’t ask for a complete rewrite upfront.

Following up regularly shows you are invested in getting the pull request merged. Work collaboratively with the author to iterate until requirements are met.

Using Code Review Tools Effectively

GitHub provides built-in tools for reviewing pull requests, but teams can benefit from additional code review tools:

LinearB GitStream

LinearB GitStream automates pull request workflows to help teams review faster. Features include:

• Auto-labeling pull requests based on content
• Adding time estimates so reviewers can prioritize
• Setting custom workflows like sending notifications
• Metrics on review throughput and cycle time

Automation reduces repetitive manual work so reviewers can focus on code quality.

GitHub Codespaces

GitHub Codespaces provide cloud development environments that make testing pull request changes fast and simple:

1. Open the pull request in a codespace.
2. Click the GitHub Pull Requests sidebar.
3. Open changed files to review and test code.
4. Add comments and feedback right in the codespace IDE.

Codespaces streamline validating proposed changes.

Linters

Linters like ESLint automatically check code for errors and style issues:

• Integrate linters with your CI system and IDE.
• Fix linter errors before submitting pull requests.
• Reviewers can see linter status rather than checking for issues.

Linters provide objective standards for code quality and style.

The right tools augment the manual review process to boost efficiency, consistency and quality.

Conclusion

Reviewing incoming pull requests is a crucial yet challenging responsibility. Following the best practices outlined in this guide leads to smoother collaboration and better code:

• Adopt collaborative mindsets – timely, constructive feedback focused on project health over egos.
• Use actionable strategies – precise language, thorough testing, reinforcing practices.
• Check all areas – code, tests, docs, configurations.
• Request changes politely – be specific, helpful and iterative.
• Leverage tools – automation, cloud environments and linters.

Great pull request reviews produce a virtuous cycle – higher quality code enables developers to get more done and improve skills, boosting team productivity, satisfaction and retention. Investing thoughtfully in the review process pays dividends across the entire engineering organization.