Code reviews – why

Code reviews are something I’ve been doing professionally for ages. It wasn’t until I was actively building development teams from the ground up that I took the time to really nail down the details of what I was trying to do and why. Nailed it down enough to explain it to someone else, anyway.

In this post, I’ll go over my perspective of the “why” of doing code reviews. And I will  follow with another post on the “how” of doing code reviews as well.

I’m writing this with the idea that you’re not a solo developer, and that you’re probably working with a team of 2 to 8 people (or even more) to collaboratively develop something. Maybe you’re building a new dev team, or maybe you’re just looking for some details on how to get better at your craft.

What is a code review?

I hope it’s not really the case any longer, but at one point when I heard code review, it gave me the impression of a bunch of grognards with neckbeards sitting around a table, ripping apart your code, and mocking you personally for a weak attempt at development. Or maybe that just shows my earlier insecurities, I’m not sure. That’s not what a code review is or should be, though.

A code review is having one or more people look over a bit of code – proposed changes, a project, or even a library you’re considering using – with the goal that at the end of the development process, your product will be better for it.

Why even do a code review?

The highest level goal of a code review is to make your product better. There’s a lot of ways that can happen, and I’ll detail out some of the below. Knowing why you’re doing code reviews, and talking with your peers or team about why you would want to do a code review is a good idea. It’s not just some random process to make things better, it has a goal, and the more that everyone understands that goal, the better you and your team will be at achieving it.

The most obvious benefit is verifying correctness. Having another person double-check what’s been created to see if it does what you say it does. When I’m writing code, I get these notions about what the code is doing and what I’m intending it to do, and what I write usually matches that – but it’s easy to miss little things in the process. If you’re working with a stricter language, maybe you’ve got a compiler to help keep you on the straight and narrow. Hopefully you’re using some continuous integration and you’ve enabled some tooling to help with static analysis and style checking. But when it comes down to the nitty-gritty of the code, tooling is only so smart – and like autocorrect on smartphones, it’s pretty dumb to context and will miss quite a bit.

If you’re code reviewing something from outside your team, maybe a library you’re about to include that you found on NPM, Github, or that your buddy told you about over a beer, then the review is more about doing what I call code archaeology. Figuring out what it’s meant to do (which hopefully you know), and how it’s really doing it. I read code all the time; even code that I don’t use. There’s always lessons to be learned there. But I digress, this is mostly about why you’re doing code reviews within your team.

The second benefit is functional knowledge sharing, or what I call “improving the bus factor“. On any team it is natural to have folks that get good at a specific topic areas – a functional component, a design, or something. But you don’t want to be stuck if that person leaves, gets sick, or is just unavailable. Then you’re in a jam, and it’s not easy to work through what’s happening there. Yeah, you can always task someone to go read through it after the fact, but then you’re already down a notch in that you can’t ask “why”, and “what did you intend for this to be doing…”.

You can in a code review, and if you don’t understand what you’re reading, you should. The huge side benefit of this knowledge sharing is cross training and learning from each other. “Hey, that’s a neat way to do that…” is something I love to hear (or read) when one developer is reviewing another’s code. Likewise, if you read through something that you think is a quick hack and would be better done another way, you can talk it through. Maybe you need the quick fix to meet a deadline, but at least it’s a known issue, not a hidden, ticking time bomb that would otherwise be missed.

On a more positive side, developers reviewing each other’s code is somewhat like jamming together musically. You get the idea of each other’s styles and riffs, and the more you do it, the easier it is to anticipate how to work together and seamlessly spin out some interesting melody.

Along with actively learning from each other, it’s a means to grow into how to work with one another, and to a large extent that’s the key benefit of a code review – it’s a point and means of actively spreading your development culture. Patterns of development, evolving architecture, coding conventions, and even social conventions are easily shared during a code review.

To summarize, the reason you’re doing code reviews:

• Verifying correctness
• Functional knowledge sharing
• Actively spreading your development culture

In my team’s post-mortems and reviews, we often talk about what we’re looking for in code reviews, and how we might want to change this or that aspect of it. Maybe it’s keeping an eye to encourage better unit testing, or making sure we keep the interfaces between two components strict so we can refactor one component or the other more easily.