We’re doing code reviews all wrong. It’s about sharing, not finding bugs.

I love reviews. When it comes to consumer equipment and whether it’s worth your money, it’s a blessing to have so much free advice to choose from. Last year I bought a new 3000-euro Casio Celviano digital piano online during the pandemic, purely based on internet reviews. Not my choice, but retail was locked down and I couldn’t try it out anywhere. Most reviews were favourable to raving, so I found safety in numbers there. Now you have to accept that reviews by retailers of their own wares are biased, but then again nobody would go to the trouble of a scathing review simply because they don’t like digital pianos, musical instruments in general or have it in for Casio as a company. Pianos are not controversial, in other words. What on earth does this have to do with code reviews? Bear with me.

Heijplaat, Port of Rotterdam

I’m also a keen reader of movie reviews, and I use them for my Netflix backlog. Twelve euros a month is incredible value for money, but boy do they have some unwatchable offal among their offerings. Rotten tomatoes to the rescue. The site uses a crude and oversimplified mechanism of scoring all reviews into a thumbs up or thumbs down and serves it up as a percentage. I found it works great for anything in the upper 20th percentile as well as the lower. I have never regretted watching a 90% movie, and I know to stay away from anything lower than thirty. It doesn’t work too well with 50-percent movies. Those tend to be controversial; the love-it-or-hate it category. It helps to skim the review excerpts to judge what camp you are in. Movie reviews are a reflection of the viewer’s emotional response as she experienced it. It’s not about subjecting ten dishwashers full of encrusted kitchenware through a rigorous cleaning cycle to see which comes out on top. There’s no checklist by which to arrive at an objective verdict and nobody expects you to do any prior research about the making of the film. Reviewers are usually just film lovers with a gift for writing, they are seldom other directors, screenwriters or actors. 

So here’s my point. Sometimes code reviews are treated like movie review: a thumbs up/down rating exercise by someone who was not involved or even interested in the creative process. I know that the analogy doesn’t hold when it comes to expertise. Code reviewers are your programming peers, but that only means that they should know better. The movie reviewer who likes to show off her literary style is like the code reviewer who thinks he’s so clever for nitpicking on small imperfections or alternatives that don’t make a real difference. This is counter-productive, not to say potentially toxic. If you review this way you may as well not do them at all. Teams that want to get along will do their best to be fair and constructive in their criticism towards each other in the knowledge that they will be on the receiving end tomorrow. This sounds plausible, but it still misses the value of a code review. The purpose is to share your work with the team, not to subject it to a quality test.

Reviews of a musical instrument or of Christopher Nolan’s Tenet are all variations on the same theme: the writer gives a verdict, and we hope they know their stuff and their opinion is not based on ignorance or spite. It’s basically a graded test. Reviewing code is not about testing that code. That should have been taken care of already. If every review yields new bugs for the backlog the work was not ready for review and you need to review your process instead. I mentioned that reviews should be about sharing. It is the stage during the development process where individual contributions become part of the team effort. It’s an active two-way transfer of knowledge. This is a world apart from the everyday meaning of review. There is no hierarchy, no master/teacher relationship and the reviewer is invested in the process: they won’t settle for a bad review. 

This knowledge transfer stage is indispensable because to deliver software as a team doesn’t mean you write every line of code as a group. That’s just not practicable. Even pair-programming is not for everybody. Many developers prefer to get into the zone on their own and that’s fine. But if you commit to deliver as a team, each member should tone down their pride of ownership over their individual contribution. Stop thinking of it as your baby already. Send it out into the world generously. The reviewer should accept this collective ownership fully and make the effort so that it becomes her code too. She is entitled to say what she likes or doesn’t like and what she feels is missing or should be changed. There is no place for pet projects, and neither for pet peeves.

A code review among fellow team-members must be an opportunity to share knowledge in at least three areas. Firstly, there’s knowledge about the new additions or alterations. The code changes can also touch on overarching domain knowledge. And there may be a thing or two to learn about generic coding practices, language/tooling features and adherence to standards that the team/organization commits to. While there will be differences in seniority, you can still learn from each other. The senior developer who has been with the project from the outset should still have their work reviewed by the new junior hire. This is not because he can’t be trusted to do his work without it, but because it’s a crucial opportunity to share and teach.