Managing expectations in code reviews
Best practices are one thing that surely matters. Improving standards is always good. Who could argue against that? But what do you expect to get from code reviews? How do you expect the experience to go? Managing these expectations, especially when it’s often so hard to measure results, can be daunting. Here are some thoughts on how to manage this.
Embrace the qualitative
Code reviews are about continuous improvement. That means it won’t always be easy (sometimes it will be impossible) to quantify how much you’ve improved. Any metric you can come up with to measure return on investment (ROI) is likely flawed, and will probably tell you as much about the quality of your other processes as the reviews themselves.
We do know some things, such as the skyrocketing costs of catching bugs later, but the value of code reviews far exceeds that of simple debugging. The kinds of improvements code reviews achieve can sometimes only be felt years later, when an entirely different team is charged with updating the codebase and finding easily readable code.
Some things you just can’t measure. We need to accept this.
Expect people will be reading you
This goes for several stages of the process. Sometimes developers will tend to forget that all their notes and comments will be read by a person that is also a teammate. A person with feelings, issues, and varying degrees of seniority and skill. Sometimes developers will tend to forget that their code will have to be read and understood by people over time.
This means you must be mindful of what you’re telling others, but also what you’re asking of them. A couple of examples:
- Massive pull requests will probably lead to shorter and more superficial comments. Is this what you want?
- Reviewers will need to place themselves. Have you provided the context that will allow them to fully understand what you’re going for?
Always keep in mind: if you’re typing it, expect someone will read it.
People make mistakes
One of the hardest things to manage regarding code reviews is the frustration that comes from reviewing bad code. Lots of mistakes, bad choices in terms of style, and unreadable code.
This, however, is almost inevitable. You’re going to have to deal with bad code sometimes.
It’s important to not let that frustration boil over into aggressive or hurtful comments. Communication must always be geared towards improvement, both of the codebase and the team. Code reviews are a great way for everyone to learn from mistakes, but that depends on the kindness of the reviewers.
Be mindful of people’s schedules
Full-time code reviewers are rare. And even if they weren’t, they would have a schedule anyway. Sometimes we expect our colleagues to pick up whatever is our priority as if it is also theirs, but that’s not how it works.
Code reviews are often treated by teams like an afterthought, something that can be done by anyone “as soon as they have a minute”. This is never the case, and reviewing is a task that should be treated with the same consideration as any other. Assign your reviews in due time, and expect people will be busy.
Best practices matter
Your expectations of code reviews should always take into account how they are being done. Are you posting the pull requests to a public channel and expecting anyone to pick them up? Then you shouldn’t be surprised no one does, or if it takes them a long time to do so. Are you bundling up all the reviews and doing them at the end of the week? Then you should expect a lot of confusion. Are you reviewing for hours on end? Expect mistakes.
The full benefit of code reviews heavily depends on them being integrated into a continuous code-review-centric operational model, and the more your practices reflect this, the more you can expect from them.
Code reviews are about your team
An underappreciated aspect of code reviews is how they are a collective endeavor. We believe in them as a form of fomenting co-ownership of the codebase, and always tell reviewers to not think of what they’re looking over as someone else’s work. It belongs to the whole team.
Code reviews, when done right, will expand the whole team’s knowledge of the product, and help everyone learn with both the mistakes and the skills of everyone else.
This is probably the most important thing you can expect from code reviews, if you make them work in that way: you can expect them to be not only a guarantor of your code’s quality, but also a true engine of team building.
What are your expectations for code reviews? Did we miss something important? Drop us a line on Twitter (@codereviewpad) and let us know!