Overview
A popular way to cut down on bugs and make sure proposed changes should be made is through code reviews. When working with teams and wanting to add your code to a repository, you open a pull request to that repo. Then other developers on your team can review your code, make comments, request changes, or, fingers crossed, approve your PR(pull request).
Reviewing a PR can be a daunting task, especially if you’re new to the process. And of course, there are things to keep in mind when making a pull request. We’ll go through both sides of the process.
Making a PR
The title of the PR should be relevant and concise. When using verbs, use the imperative form. Add a description that lets the reviewer know the what, why, and how this code is a positive addition to the feature. Keeping pull requests small helps to not overwhelm reviewers, as well as continuous deployment helps trim down on “the second 90%”. An article from SmartBear, Best Practices for Code Review, saw that efficiency in a code review greatly diminishes after exceeding 400 lines of code. To get a bit more specific, they found,
“In practice, a review of 200-400 LOC over 60 to 90 minutes should yield 70-90% defect discovery.”
Comments giving context to changes add to efficiency both by helping the developer spot their bugs and helping the reviewer understand the code’s purpose.
Streamlining
Code reviews should not be used to nitpick formatting. Use formatters and linters, these save large amounts of time. These will have to be set up at the beginning of a project, then developers no longer need to spend time arguing about spacing or other minor syntactical issues. As long as you remember to use your formatter! In this same vein, avoid wasting time arguing about variable names. Focus on the important stuff. It’ll be easier and more tempting to point out the easy things, like syntax and naming, but they won’t impact the performance or how the new feature works.
Tests should only stay in the codebase if they are helpful. Good tests help ensure merges won’t break the production instance. Don’t keep tests that just slow the team down.
Most effective uses for code reviews
A developer is new to the company or still a green developer. Code reviews in this case will teach the newbie the company’s styles and conventions. This can also be used the opposite way. A developer new to the repository can review a pull request to better understand the conventions or the new feature.
If making changes to integral or sensitive parts of the code base. Examples would be changing the architectural structure or dealing with sensitive data. While these instances should be less frequent, you’ll want extra eyes on the pull request to double-check it won’t take down the site or add vulnerabilities.
When it seems like a whole discussion is breaking out in the comments, that’s a sign to schedule a meeting. What could end up being a giant thread of unproductive messages, could be more efficient by a quick meetup.
Reviewing Code
Be nice, and add encouragement.
In A zen manifesto for effective code reviews, Jean-Charles Fabre wrote,
“Did you know that in written communication, neutral content looks more negative than it actually is? Beware of this bias and include emojis when needed to get the tone right in your comments.”
There’s no reason to lower morale by not considering other’s
feelings. When seeing areas for improvement, use language
that promotes a conversation. If you have an idea to improve
something, ask what they think about that idea, instead of
asking why they haven’t already implemented it. This is
kinder and gives the reviewer more context to the decisions
made. Both parties can learn more from questions than
requests.
- Be engaging, if you’re confused about something, ask questions. If you have other ideas, feel free to suggest them and weigh out the pros and cons. Always reach out with helpful resources!
- Junior developers should still feel comfortable giving code reviews to their senior developers. Letting someone know you found something confusing might point them towards refactoring to something better.
- Keep up with pull requests; getting to a review late will make it more difficult for the reviewee to remember exactly what they were doing.
- Make sure the outcome of the code is in line with the purpose of the pull request.
Things to avoid
- Your style opinions are not fact, and should not be presented as such. If you’ve got documentation or style guides that back you up, you can give a reference to the documentation.
- Don’t overwhelm the contributor with comments, if they’re following a poor pattern, reference the poor pattern instead of leaving a comment on every single instance of it.
- Don’t comment on code they didn’t write. If they worked on a feature that had some bad code in it, don’t try and force them to fix it. What you can do is review what they worked on and say you’d like to come back to the previous poorly written section.
- Judgmental phrasing. You want to build up your peers and help improve the overall product as a team. Pay attention to phrasing. Instead of asking why they didn’t do it the way you would’ve or being sarcastic, let them know another way, and what the benefit would be.
- Don’t use emojis for comments, unless they’re positive. The positive emojis can be encouraging and fun, but if leaving an emoji to point out something negative; you aren’t explaining why and it can come off as mean.
- Ignoring comments. Someone took the time to read your pull request and try to help you improve it. Be respectful to your other developers. If it’s advice you don’t want to implement, you should still respond and maybe let them know why not.
Outro
If you were like me and overwhelmed when first tasked with reviewing a peer’s code, hopefully, you should now feel confident to get out and start reviewing! Regardless, with some new techniques for code reviews, you’ll know how to get at them more effectively! Thanks for reading!
Top comments (0)