A Guide to Healthy Code Reviews

Regardless of where I've been in my career, teams tend to come to the same conclusion about what makes for a healthy code review.

Given how often code reviews happen, it's important to recognize that the tone we set in reviews will impact the overall team culture and we should be mindful of keeping things positive, constructive, and collaborative.

Roles

As a member of a team, we all play a part in this process and we're all striving towards the same goal.

Author

As the author of a pull request, it's important to set things up as well as you can when presenting changes to the team:

• Keep the number of line changes to a certain limit (a smaller change set doesn't necessarily mean less complexity, but a larger change set may require more time to go through - look for a balance that works for your team)
• Separate refactoring efforts from core functional changes
• Give proper context for changes
• Add supportive documentation i.e. usage examples, diagrams, etc.
• Add unit and integration tests
• Add in in-line comments to highlight questions, trickier parts of logic, etc.
• Be open and responsive to feedback

Reviewers

As a reviewer, your role is there to support your team members efforts:

• Be thorough and spend time to understand the changes
• Ask questions when things are unclear
• Help identify gaps in logic, if any
• Ensure changes are consistent with established team guidelines
• Be open and responsive to feedback

Hiccups

Even with a well-tuned process, reviews can stall out. There are a lot of reasons why this happens. This could include:

• The number of lines changed is too large
• The changes are confusing
• A particular aspect of the change has sparked lengthy debate

In my experience, I've found it helpful to ask myself the following questions when things are stuck:

• Does the pull request need to be broken down into multiple parts?
• Should we hold a quick meeting to get past a particular point?

Final Notes

Each review is also an opportunity to educate each other and figure out what the best path forward is for the team when more nebulous questions arise.

If you feel like your code review process might not be as efficient as you would like or lacking in some area, definitely reach out to your team and brainstorm what you can all do moving forward to make things better.

Other teams at work or friends can be fantastic resources as well. Reach out and compare notes. At the end of the day, we're all doing the same thing and can help each other.