Reviewer Guide

Notification

Keep an eye on your notifications for new PRs assigned to you or those that require review.

Contextual Review

Check the PR description, title, and any related issue tickets to understand the context of the changes being proposed.

Browse the Changes

• Open the PR in GitHub and navigate to the “Files changed” tab to see a side-by-side comparison of the changes made.
• Use GitHub’s diff viewer to examine modifications that are being proposed.

Review the Code Against Criteria

Evaluate the code based on the following best practices:

• Functionality: Does the code achieve its intended purpose without introducing bugs?
• Readability: Is the code clear and easy to understand? Are variable and function names descriptive?
• Adherence to Standards: Does the code follow established coding standards and style guides?
• Efficiency: Are there any performance issues or optimizations that can be suggested?
• Testing: Are there adequate unit tests, and do they pass successfully? Is there good coverage for edge cases?
• Security: Are there any potential security vulnerabilities that need to be addressed?

Leave Comments

• Use inline comments to point out specific lines of code where feedback is needed.
• Be specific and provide clear reasons for your suggestions or concerns.
• Highlight positive aspects of the code as well to encourage the author.

Avoid Ad-Hoc Comments

When reviewing, aim to complete a thorough analysis of the code before submitting comments. Try to refrain from leaving ad-hoc comments as you review. Instead, use the “Start a review” feature to add pending comments until you have finished the entire review. This approach helps maintain clarity for the author, preventing them from mistakenly believing the review is complete. It can also reduce back-and-forth communication, making the process more efficient for both the author and the reviewers.

Prioritize Feedback

Differentiate between critical issues that must be resolved before merging and suggestions that are optional for the author to consider.

Clarify Questions

If you encounter something unclear, don’t hesitate to ask the author questions about their implementation to understand their thought process better.

Encourage Dialogue

Foster an open environment for discussion. Exchange ideas with the author and other reviewers to arrive at the best solutions collaboratively.

Approval

If you are satisfied with the code and all issues have been addressed, approve the PR. In GitHub, this is typically done by clicking the “Approve” button.

Recommend Changes

If critical issues remain unresolved, leave a comment detailing the required fixes. Be specific about the aspects that need improvement, providing clear reasoning for your suggestions.

Patience

Allow time for the author to implement the requested changes. Reviewers should be aware that the author may need time to address feedback and re-test their code.

Re-review

Once the author has made the requested changes, conduct a re-review of the updated PR to ensure all feedback has been adequately addressed.

Final Review

If authorized (or the lead reviewer), double-check that all concerns have been addressed and that all tests pass.

Merge the PR

Follow your team’s merging process. This may include squashing, rebasing, or merging directly into the main branch, depending on your project workflow.

Reflect on the Review Process

After the PR is merged, take a moment to consider the review process. What went well? Were there areas of the review that could be improved?

Provide Feedback

If the team holds retrospectives or discussions about the review processes, share your thoughts to help refine the approach in the future.