A code review is a process in which developers collaborate on proposed changes to a codebase. Code reviews are an integral, dare I say, essential part of a healthy software development workflow. As with any written work, a peer review improves the quality of the finished product. In the technical space, this translates to a product that is more reliable, resilient, and scalable.
The following are some suggestions for making code reviews more useful and enjoyable:
Define a purpose
If we do something enough times, we tend to forget why we started in the first place. Establish consensus with your team on the value code reviews add to your organization as well as the appropriate intensity level they deserve. Motivations might include: catching bugs early, sharing knowledge amongst developers, and minimizing technical debt. Save valuable engineering time by automating boilerplate checks such as conventions and test coverage (at CareMessage, we employ Code Climate for the former and Codecov for the latter). Having goals in mind keeps the process focused and efficient. Without them, it is easy to get lost on tangents and cosmetics. Once these are established, build metrics around them and continuously audit your process for improvement.
Dedicate time and energy
Armed with the conviction that code reviews are important, be sure to give them their proper right. Know that reviewing code is not a trivial or shallow task. Rather, it is real work that should be budgeted into your day. If following an agile process, factor code review into your point estimation and address issues with the process during retrospectives. Finally, beware of code review fatigue. It is better to deliver a good code review later than a mediocre one now. Be mindful, however, of not blocking another team member. If your team is large enough, you can always ask someone else to fill in.
Be a good code reviewee
Ready to review some code? Not so fast. Before delivering feedback to others, make sure you are able to receive it from them.
Be the reviewer you want feedback from and the author you want to deliver feedback to.
Being on the other side of the fence will help you appreciate the author’s perspective. Furthermore, your teammates will be much more receptive to your feedback if you are equally receptive to theirs. Embrace the idea that someone is helping you improve your work and don’t be afraid start over. Recall that everyone is on the same team and cleaning up code is a win-win. This point is especially relevant as a new team member; give yourself a chance to learn a company’s code review culture before diving in.
Self code review
Building on the previous point, code reviews will go a lot quicker if authors review their own code before sharing with the team. Using a diff tool (such as an IDE plugin), you can preview how others will see your work and adjust as needed. After working with the same people for a while, you begin to anticipate their feedback so pretending to be them for a few minutes can save some review cycles. When ready to submit, ensure the commit log is clean and pull request description is clear (we use a PR template with fields for description, issue reference, and QA steps). Annotate your code with key decisions you made and areas that deserve a closer look. Be mindful of the diff size as large changes can be cumbersome to review. Data suggests that ~400 lines is a good upper limit. If pull requests are regularly large, consider breaking your stories into smaller deliverables.
Review code not the coder
When reviewing code, direct your comments at it rather than its author. Create a culture that celebrates finding issues; if code was always perfect we would not need a review in the first place. Keep comments objective and back things up when appropriate. Official docs, READMEs, GitHub issues, and Stack Overflow accepted answers are great references for best practices. Consider creating a code review checklist with the goals you outlined in the first step. In addition, pulling the code locally can help put you in the author’s shoes and allow you to try things out before suggesting them. If capturing metrics, use them to analyze and improve the process as a whole rather than assign blame. Better yet, anonymize this data to encourage candid feedback.
Create a conversation
As developers, we are pretty good at talking to machines but sometimes fail in human interaction. Keep this in mind when critiquing another engineer’s work and leave room for personalities. If unsure of something, give the author the benefit of the doubt. Phrase your comments as suggestions and questions to encourage a back and forth dialogue. Beware of having too many code reviewers as this can lead to too many cooks in the kitchen with nothing done. Two reviewers seems to be a good number; this limits personal bias and creates a natural tie-breaking effect. Finally, code reviews need not be formal or within the context of your code review tool. Be liberal with discussing code in less conventional settings such as Slack or on a white board. This is especially useful for gathering feedback before a major change or brainstorming when you get stuck.
Hire good code reviewers
Given the importance of code reviews, and how much of an engineer’s time is dedicated to them, I encourage code reviewing be part of the developer interview process. If you are seriously considering a candidate, have him or her participate in a code review exercise with prospective teammates: both as a reviewer and an author. This touches almost every skill you care about such as communication, coding, team-work, confidence, …etc.
In conclusion, code reviews are a valuable tool for most software projects. As with any tool, however, they are useful when done right but can be deadly if implemented poorly. If you have more ideas for effective code reviews, I’d love to hear from you below.
Happy code reviewing!
