Great Code Reviews: Writing and Reviewing Pull Requests Effectively

The benefits of code reviews are plenty: someone spot checks your work for errors, they get to learn from your solution, and the collaboration helps to improve the organization’s overall approach to tooling and automation. If you’re not currently doing code reviews in your organization, start now. It will make everyone a better engineer.

Good code reviews start with good Pull Requests. It is the developing engineer’s responsibility to set up the reviewer for success by clearly documenting the changes and the expected behavior.

Well-formed Pull Requests should include:

1. The purpose of this Pull Request. For example:
   • Spike to explore…
   • Simplify the display of…
   • Fix handling of…
2. Use the present imperative tense. For example, use “Fix dashboard typo” instead of “Fixed” or “Fixes.”
3. Be explicit about what feedback you want, if any. Perhaps you only need a quick pair of eyes on the code, or you need a discussion on the technical approach, design critique, or copy review.
4. Be explicit about when you want feedback. If the Pull Request is work in progress, say so. A prefix of “[WIP]” in the title is a simple, common pattern to indicate that state.
5. @mention individuals or teams that you specifically want to involve in the discussion, and mention why.
   • Example: “/cc @jesseplusplus for clarification on this logic”
   • Example: “/cc @github/security, any concerns with this approach?”
6. Include steps to test the change. Make it simple for reviewers to verify the functionality.
7. Include video, screenshots, or any other important elements that can help reviewers quickly understand the changes.

Good code reviews look at the change itself and how it fits into the codebase. They will check the clarity of the title and description and make sure the “why” of the change is clear. They cover the correctness of the code, test coverage, functionality changes, and confirm that coding guides and best practices are followed. Furthermore, they will point out obvious improvements, such as hard to understand code, unclear names, commented out code, untested code, or unhandled edge cases. They also note when too many changes are crammed into one review, suggesting that code changes remain single purposed and, if necessary, be broken into more focused parts.

Code Review Checklist

• Branch and commit names are correct
• Code is readable
• Style guides and naming conventions are followed
• Folders or files structure is reasonable
• Code is structured well. No classes or functions should be broken down further
• Covered with tests
• Documentation is created

Keep the tone positive!

Good code reviews ask open-ended questions rather than making strong or opinionated statements. They offer alternatives and possible workarounds that might work better for the situation. These reviews assume the reviewer might be missing something and ask for clarification first instead of immediately pushing for a correction.

Better code reviews are also empathetic. They recognize that the person writing the code spent a lot of time and effort on this change. These code reviews are kind and unassuming. They applaud nice solutions and maintain a positive attitude overall.

Defects found in peer review are not an acceptable rubric by which to evaluate team members. Reports pulled from peer code reviews should never be used in performance reports. If personal metrics become a basis for compensation or promotion, developers will become hostile toward the process and naturally focus on improving personal metrics rather than writing better overall code.

Additional Best Practices

1. Use Automated Checks and CI/CD
   Set up automated linting, testing, security scanning, and style checks so that code reviews can focus on logic, design, and maintainability rather than catching basic errors.
2. Keep Pull Requests Manageable
   Large, monolithic Pull Requests are harder to review and can cause delays. Encourage smaller, more focused Pull Requests that are easier to understand and revert if necessary.
3. Leverage Code Owners
   If your platform supports code owners, designate subject-matter experts for specific parts of the codebase so that domain knowledge is applied when reviewing specialized changes.
4. Consider Security and Performance
   Reviewers should look for potential security vulnerabilities, performance bottlenecks, and data privacy concerns. If you see something that could pose a risk, call it out and provide suggestions on how to address it.
5. Document and Share Knowledge
   Encourage reviewers to ask clarifying questions and share relevant documentation or articles. This helps the entire team learn from one another and ensures knowledge does not become siloed.
6. Follow Up and Iterate
   Once the initial review is complete, the author should address any feedback and follow up with reviewers as needed. If suggestions are declined, offer a concise explanation so there is mutual understanding and consensus.
7. Promote Pairing and Discussion
   For tricky or high-impact changes, consider pairing with the reviewer for a brief walkthrough. Real-time collaboration can clear up misunderstandings and speed up the feedback loop.

By integrating these best practices into your workflow, you will make code reviews smoother, more comprehensive, and more positive for everyone involved. Happy reviewing!