Code review is both the most difficult and the most critical part of a developer's job. It's the way great code happens. But to get there, we have to get inside someone else's head and ask, why did they write this code this way? And then, after we thoroughly understand it: is there any way it could be better? Once we have that figured out, we still need to communicate it back to our fellow developer in a way that is clear, productive, and empathetic.
I strive to achieve that balance by following these guidelines, inspired by my code review experiences:
1) Code reviews are a teaching opportunity.
Always explain why you're requesting a change, not only out of respect for the code author's time and intelligence, but also so that they will be better prepared for the next time they encounter the same issue. It helps to add links to any resources that could help explain concepts or patterns, and any tools that you're recommending.
2) Code reviews are a learning opportunity.
If any of the code you're reviewing is new to you, or structured in a way that's unfamiliar, note it and look it up. Research if it's a best practice you should be aware of. If it is, incorporate it into your own code.
3) Code review comments are not the place to have a discussion.
As soon as the code author writes back to ask a question or make an argument, it's time to move the conversation out of the code review. Find a time that works for both of you and schedule a pairing session to hash it out.
4) Use your code review to fight scope creep, not encourage it.
If a PR covers more work than the original issue or is difficult to review because of its size, flag that so the team can learn to avoid it in future. Think about ways the PR can be reduced in size, rather than expanded. Avoid the temptation to suggest changes to surrounding code, or reformats based on new style rules. Open new issues for these and unrelated bugs.
5) Don't Repeat Yourself.
If you catch an issue that reoccurs in multiple places in the code you're reviewing, point it out once and ask the code author to address any other instances. This demonstrates your trust in their abilities while allowing them to have the learning experience of finding and fixing the problem themselves, which will enhance their retention for next time.
6) Be kind, always.
“Everyone is fighting a battle you know nothing about." Keep your review positive and your language upbeat. Remember how it feels to receive criticism, and review the way you'd like to be reviewed.
Further reading: How to Make Good Code Reviews Better
Top comments (0)