Code reviews are a daily occurrence for software developers. It can be a crushing learning experience, but it can also turn into a selfish process. Here are a few tips to help you become a more successful and decisive reviewer.
Structuring pull requests to make life easier
Avoid huge changelogs
- Keep the change log as small as possible.
- If your changelog is longer than 600 lines, try breaking it down into smaller clear parts that can be reviewed separately.
- Nobody wants to receive a 1000+ line pull request monster. Good reviewers often reject pull requests of this size as they know from experience that they likely won't be able to review it adequately.
Structure to understand
- Bunch similar changes into commits. Did you change the location of multiple files without altering them? Group these changes into the same commit so that the reviewer knows they are not logical changes they must focus on.
- Commit your changes frequently to reduce its scope. It is much easier for reviewers to focus on what's important when commits are small than when dealing with larger commits.
Stop possible confusion
If you change the logic or structure that existed in preceding commits, you should inform reviewers so that they are not distracted by criticizing code that does not exist anymore. This applies when reviewers go through commits one by one.
Provide sufficient context
Make sure the pull request is clearly explained, either through a linked ticket or through a written explanation in the pull request, or preferably both. Provide visual or other examples of how your work affects the project. Try to see things from the reviewer's point of view and make it as easy as possible to understand the purpose of the pull request.
Effective access to team member's PR
Timely review
- Try to review a pull request as soon as you are added as a reviewer.
- The maximum time from a pull request to completion of first review must not exceed 1 business day.
Gather context if missing
If a pull request is missing context or a description of all changes, contact the author for clarification before reviewing. This can greatly reduce discussions due to misinterpretations of the code or its purpose.
Start at high level
Review from the high level down. Don’t comment on small changes like styling until any large issues are dealt with. This allows authors to focus on the most important fixes first. Sometimes small problems go away along with the bigger changes.
Disagreement handling
If you disagree with the code block, provide a code example of how you suggest it should be done. It is much more helpful to other developers than leaving a "this should be different" comment.
Change request
Do not block pull requests unless there are fundamental problems. Putting an obstacle in front of your colleague over an argument around naming does not help anyone on the team. Give your team the opportunity to review small changes and continue working without waiting for the next piece of feedback.
Empathy
Most importantly, remember there is another person at the other side of the review. Provide feedback in a useful and constructive manner. Always think about how you would like to receive feedback if it was pull request being reviewed.
