Tips and tricks for acing your first peer code review
What makes a code review – an actual code review, and not just a set of stylistic notes about inconsistent white space or curly braces? The base-line standard for writing legible code is that what you write doesn’t just need to work, it needs to be understandable. That is, someone should be able to go directly into your codebase and read it. So, in order to make sure your code works, a systemic form of checking it needs to come into play.
Because programming is, after all, written by humans, it’s prone to errors that other humans can help catch – architecture, bugs, structural errors, and inconsistency are top of mind during reviews. So, while running your code through an automated tool is certainly helpful, it should never be a substitute for a code review.
Not only do peer code reviews allow for a system of checks and balances, but they actually foster a culture of camaraderie and mentorship across teams. Just as a senior engineer can provide a set of seasoned eyes, newer developers can bring new perspectives that re-evaluate dated parts of the codebase. What’s more is that the methodologies for code reviews today have evolved, and aren’t nearly as time-consuming as they used to be – no fear, beloved Agile testing.
Finding and correcting bugs during development is a lot quicker and easier than finding bugs during testing, not to mention less expensive. Going back into a codebase once an application gets merged upstream is much more difficult. So, when executed and scheduled correctly, code reviews actually save engineers time in the long run.
Modern teams have shifted from time-consuming, formal code review processes coined back in the ’70s – dubbed the Fagan Inspection – and have instead turned to a methodology that involves regular, change-based reviews. You’ll encounter code reviews in all shapes and sizes but will more or less follow the same formats you should familiarize yourself with.
The most commonly encountered and effective style of code review is tool-assisted: tool-assisted code reviews integrate peer reviews with available software – these are useful for providing a collaborative space for programmers to compare versions, comment, and report on their progress. Afterward, you might have a few conversations or do an over-the-shoulder review with a teammate. It’s important to note that no matter the specific review process, there will always be at least two parties at play in lightweight reviews: the author, and the reviewer. In the next section of this post, we’ll dive into some pro-tips for being on either side.
Taking a code review from good to great is a two-fold endeavor: having a solid grasp of technical best practices is equally important as is having solid code review etiquette. In fact, communication – both digital and in-person – is what can make or break team productivity in a code review lifecycle.
In this section, we’ll review some best practices that you should keep in mind when prepping for your first team-wide code review – both as a reviewer and a reviewee.
Request specific feedback. Communicate to your reviewer what they should focus on by annotating your source code. Before sending your code out for review, it’s imperative to spend some time going through it with a clear vision of which sections need special attention – and why. Annotate your code with clear indications and notes of which files your reviewers should prioritize, and use this as an opportunity to provide some context about your process and workflow, as well as note any areas you might be struggling with.
Use checklists to set goals and metrics. A well-prepared team will create clear-cut goals around testing and reviews by creating guidelines for review and style guides – these help structure a workflow for review and make sure no steps get overlooked. Before diving into peer reviews – providing your reviewer with a checklist of required features and commonly made errors can go a long way in establishing thoroughness. After all, it’s a lot harder to review something that accidentally got omitted.
Mostly, this preparation is a hidden opportunity to review your own code with eagle eyes one last time before passing it along the pipeline!
Equally important is setting a few guidelines for yourself when you’re on the other side of code reviews: multiple data studies have led to the following three general best-practice rules when reviewing others’ code.
Review less than 400 lines of code (LOC) at a time – structuring your review sessions into frameable chunks will help keep you focused.
Take your time: it should take you about an hour to get through 500 LOC.
Limit your review time to 60 minutes per session – take breaks to recharge and press the mental reset button before diving back in.
It’s easy to fall into the pressure of wanting to get as much done as quickly as possible, but rushing through a code review has proven to actually diminish defect discovery. Overall, a familiar strategy rings true: be patient. Make sure you give yourself (and your mind) time to process the information, especially if you’re just starting out.
Just as you would for your own code, practice setting up a checklist of what to look out for when reviewing. While formatting, style, and naming are good places to start, make sure your focus is on identifying common bugs. Some examples include:
Whether giving or responding to feedback, handling peer reviews with grace is trickier than it seems: lots of critique goes into the process, and as a junior developer, you’ll have to get used to killing your darlings from time to time. As you review, make sure you keep the primary goal in mind: the code needs to work! Getting nitpicky about formatting or design changes can end up slowing the process down.
A good frame of mind to maintain during the code review process – no matter which side you’re on – is treating every bug as an opportunity to learn and improve your skillset. Understanding how to engage with, and provide, feedback during code reviews is a skill equally important to your technical knowledge – here are a few best practices to keep in mind.
Critique the code, not the coder.
You’ve probably heard the expression – you are not your code. This is an incredibly important reminder as you navigate around correcting your own mistakes or noticing others’. When you comment on someone’s code, a good starting point is to keep pronouns out of your language: try to avoid saying something like ‘your code has a bug here’ or ‘my style worked better’. Using language like this distracts from finding errors, as it triggers the automatic reaction to defend your work. Instead of speaking with generalizations such as ‘this is always the better strategy’ – try to suggest changes that are more open-ended, such as ‘consider this change that we’ve made work before’. Finally, make sure you differentiate between your personal suggestions and required changes in your comments – a good tip is to keep clear-cut directions concise, and go more in depth about things that you have opinions about, and provide additional links or information to clarify.
Respond proactively, not reactively.
Remember that your reviewer is on your side – they’re not there to offend you or try to upstage your work. Make sure that you address all comments and consider suggestions, regardless of whether you agree or not. Including just a simple one-word confirmation that you’ve addressed a change goes a long way in acknowledging your reviewer’s time and work. If you find that you and your reviewer have hit a road-block in going back and forth, learn when to take the conversation offline – in-person communication is key to settling strategic debates or complex changes.
After all, not only are you getting the valuable time and insight from mentors who have grappled with many a source code, but you are united in your goal of creating something that makes your product work for years to come.
Simona Galant is a freelance writer. You can find her work on AngelList, Samsung, and Springboard.