An Ode to Code Reviews
Tags: codereviews, teamwork, developerproductivity
Published: 2020-01-21 10:23:21

---
title: An Ode to Code Reviews
published: true
date: 21-01-2020
tags: code-reviews, teamwork, developer-productivity
description: Code Reviews are hard by nature, especially in a multi-project company. In this article, we explore why we do them, how to do them properly, and we introduce a new idea: the Review Buddy.
canonical_url: https://www.codegram.com/blog/an-ode-to-code-reviews/
cover_image: https://www.codegram.com/assets/static/an-ode-to-code-reviews.a98966c.2664713909e44e452b2d6fe6b440815e.jpg
---

At [Codegram](https://www.codegram.com), we truly believe that **Code Reviews** are a **crucial activity** in any software development endeavor. That's a mantra we've been repeating over and over inside our company, but honestly, we think we can get way better at it.

This article is an ode to the beauties of **Code Reviews** and how they can make your team share **better** & be more **accountable** for its decisions while making it all more **enjoyable** for everyone. We'll explore why peer reviews matter and we'll introduce an idea — the _Review Buddy_ — to help you improve the way you review code as a team. But first...

## ❓What even is a Code Review?

Code Reviews are a **quality assurance** process in which a developer exposes their code to an individual or a team in order to get feedback and change it until a consensus is achieved. Depending on your tool of choice, you're going to use GitHub's [Pull Requests](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests), GitLab's [Merge Requests](https://docs.gitlab.com/ee/user/project/merge_requests/) and so on.

## 🙃 But why code review at all?

We developers love code so much that **we'd probably rather spend all day throwing lines at the editor** , leaving aside other mundane activities like meetings, answering e-mails or... reviewing other people's code.

That's okay and sure everybody can understand that feeling. We just love code _so much_! But writing code is not a science but rather an engineering task (some might say there's even some art in it), and successful engineers take the human factor into account **every step of the way.**

> "Taking the human factor into account". A-ha.

See, what's made of a bunch of humans? Teams! So let's take a step back and think about what we're collaborating over: **_code_**. If we look at programming languages themselves, they're not meant to _just_ solve the problem at hand, they're also meant to be _expressive, clean_ and _reusable_. Arguably, sometimes at the expense of efficiency solving the problem itself.

Why is that? Because **we care about how other humans** (or the future human you!) **deal with code** so they can understand it, build on top of it, extend it and re-shape it as pleased.

If you think about it, _code reviews_ are the ultimate form of expressiveness. They just happen to encompass another dimension: **time**. When you create a _Pull Request_ on _GitHub_, you do it to solve a specific need _at that moment in time_, with a specific context in mind that might change in the future.

Maybe a colleague — or yourself — need to revisit a decision you made a while ago and hey, revisiting that nice **Pull Request** might just be what you need.

You might be thinking: Okay, so code reviews are mainly a bookkeeping tool. Yes and no! They are **way more powerful than that.** Keep reading to know why (mini-clickbait) 👇🏼!

## 🧠 Code Reviews help with knowledge transfer.

If you're reading this, you're probably the **curious** type. Being curious in the tech industry usually means constantly looking for new & effective solutions to solve your everyday problems, or even trying to jump to _that new cool framework_ and going for a quick ride on the _hype_ train.

What's better for that than being able to see what other _humans_ are doing? Code Reviews enable precisely this - the ability to peek into someone else's code to learn new stuff.

## 🤝 Code Reviews create a sense of shared responsibility.

**Continuously having to make decisions on your own** on a piece of code without any help, let alone a whole project is **mentally draining & stressful**. By having others review your code, you'll be able to get some relief while knowing there'll be someone else there for you in times of need. ~~And that can be the start of a friendship that lasts forever.~~

## 👀 Code Reviews will improve code quality even when nobody is watching.

You might be familiar with the "rubber duck debugging" technique, a concept introduced in _[The Pragmatic Programmer](https://pragprog.com/book/tpp20/the-pragmatic-programmer-20th-anniversary-edition)_ book. Dave Thomas, the author, makes a case on how the mere act of **explaining** code to a peer can help you debug a problem without any actual interaction needed — so we might as well be talking to a rubber duck 🦆.

I like to think the same principle applies to Code Reviews as well. By writing code as if someone would review it (even it that doesn't happen), you're going to **write better code**.

**\*Rule of thumb:** Assume you always have a bunch of ducks around when writing and delivering code.\*

> But the humans...?

Ok, back to the main point! When you **do** get your code reviewed by other humans:

- **You gain a better understanding** of your own decisions by being questioned over them.
- **You will get useful contributions** that can help to fix bugs, to find new edge cases, and maybe even lead to rethinking a flawed architecture.
- **You will learn from people** that might have more experience or insights about a particular area.

## 🤩 OMG Code reviews are so cool!
 ![](https://www.codegram.com/blog/an-ode-to-code-reviews/allthethings.png)<small>Code Review all the things!</small>

...so **why don't we do it more often**? Well, I think that's because coming up with an effective way to present & review code is **hard by nature.** And because of that, some people see it as a burden and put it in the same box as _reading e-mails_ or _attending meetings_.

Let me introduce you to some advice on how Pull Requests need to be dealt with at the grass-roots level, and then we can talk about _team dynamics_, which is a whole different thing.

## 🦄 Here's how to step up your code reviewing game

> There are three sides to every story: yours, mine & the truth.— _anonymous_, but also the title of a [rock album](https://open.spotify.com/album/2TV8JqednqRKb2injBMYGd) I really like

### As an author, you should:

- **Be verbose and provide enough context:** A Pull Request needs to have a clear structure & description. More than _what_ and _how —_ which can often be guessed by the code itself — one must focus on the _Why_. Why did you choose a particular path? Were you under a tight deadline and did you have to compromise? Whom does it affect? Does this affect any business logic?
- **Write tests:** Tests are a great way to express the boundaries of a problem and provide specific examples of how the code behaves in real-life scenarios. Reviewers will appreciate having them gain a better understanding (and your customers probably will too, but that's another story)!
- **Checks, checks everywhere:** GitHub, GitLab, et al allow for automated checks such as linters, code coverage analysis, and others to be embedded just within your Pull Request. By doing that, we leave some low-value topics such as styling out of the conversation and let our dear reviewers focus on what's important.
- **Get your Pull Request deployed somewhere** : Sometimes _seeing_ something is better than just reading about its internals. Using tools like [Heroku's Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps) or [Netlify's Deploy Previews](https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/) can be really helpful, providing a separate deployment _per Pull Request_.
- **Don't let your Pull Requests block your progress** : Quality code reviews take some time and you don't want to rush people into accepting them just because they're blocking you. If you're being smart about it, you'll have come up with an architecture that will allow you to have **multiple Pull Requests going on** without one depending on another. It takes some practice and it's not always possible, but it's definitely worth the effort!
- **Don't take criticism personally:** When getting your code reviewed, you might sometimes feel personally attacked. That feeling might come from a vulnerable position — _am I not smart enough?_ — or even from a defensive position — _they're over their head_! Just keep in mind _you_ are not your _code._ Take a breathe and remember: they're challenging **your code, not you**.
- **Be cooperative:** Even if you think a reviewer's suggestion isn't _right_, be cooperative and walk them along with _why_ you think that's the case. Dismissing another person's opinions just because isn't nice — think about how you'd want to be treated if the situation was reversed. Plus, if you think the issue lies in the reviewer not understanding the problem at hand, chances are you didn't provide enough context, to begin with.

### As a reviewer, you should:

- **Be empathetic:** Keep in mind a Pull Request done properly took a lot of effort. You'll get a way better conversation if you keep an upbeat, engaging tone in your comments.
- **Write thoughtful, unambiguous comments:** Tone is difficult to grasp on written communication. Be sure you don't leave space for ambiguity and that your writing is clear & concise while providing enough context.
- **Suggest specific changes** : If you think something can be improved, don't just say so, suggest a specific change. But again, don't _just_ suggest a change, it can stike the other side as passive-aggressive. Take some time to explain _why_ you think something can be changed.
- **Don't be judgmental:** There are lots of reasons why code doesn't look _the way you think it should look_. Don't make judgments and try to understand why they came up with that particular solution. After all, you're both aiming at the same goal.
- **If you need it, download the code and run it:** Superficial reviews are not useful at all. It's a temptation you need to fight. If you need to, download the code and run it. It's fun!
- **Beware of the impostor syndrome:** Have confidence in your feelings on the code and don't be afraid to start a discussion, even when reviewing more experienced developers' code. Also, comments on Code Reviews don't always need to be about suggestions - asking questions to gain better understanding of what's happening is perfectly fine.
- **Be responsive:** When asking for changes, don't just leave and come back days after just to find your suggestions addressed in a couple of minutes. That's not nice. Just keep on top of what you review so everybody can get done with it!

## 🖖 Nice tips! Give me my CodeReviewMaster© shirt already.

Well, wait a minute. These tips & tricks are really cool, but for these to work, **Code Reviews need to actually _happen_**. As it turns out, that isn't always that easy. It certainly isn't for us, being a consultancy that works in lots of different projects at the same time. Why is that?

On one hand, **when working within a really small team, getting quality code reviews can be hard:** Imagine you're working on a project and you're the only front-end developer. Who can review your outstanding _Vue.js_ code if there's no one else in the team that knows about it? You could always ask someone else outside of the team, but then, on the other hand, **collaboration cross-project is just tedious.** Creating a `#code-reviews` channel on Slack where everybody can go get their PRs reviewed looked like a nice idea at first, but doesn't really cut it. You can't possibly get valuable reviews out of them -- reviewers are missing a lot of context due to them not being actively involved on the project. Soon enough, the channel ends up being cluttered of unanswered cries for help and, eventually, people stop asking for reviews at all.

One **could reach the conclusion that Code Reviews can only happen in mid-sized teams and up** , and that collaborating outside of the team's boundaries is just a pipe dream. A sad reality to live in.

## 😓 So we're doomed. Back to writing code alone in the dark.
 ![](https://www.codegram.com/blog/an-ode-to-code-reviews/blanket.png)<small>Coding alone with a blanket at night</small>

Please don't close this tab yet! We've come up with ways to **get your Code Reviews** _to be way more effective_! Or at least, we think so 😏.

We're about to change how we collaborate over code at Codegram and we expect this will lead to improved _team dynamics_ (see! I said we would talk about it). **Code Reviews are about to be second-class citizens no longer**. Here's our plan:

1. **Every developer working alone on a project or in an area will get a _review buddy_** : A _review buddy_ might not need to be involved in the actual coding, but will be there to **preventing PRs from becoming stale** with their helpful reviews. A _review buddy_ knows about the history of a project and thus understands all the decisions behind every step taken, leading to in-depth, spot-on appreciations. A _review buddy_ has no reason to ignore your PRs. A _review buddy_ is your best friend.
2. **Developers can still ask someone else for help:** In the event that a developer and their _review buddy_ (I love this name) are stuck, they can always ask for help to someone else — since they won't receive a constant stream of impersonal review requests anymore, they'll appreciate being chosen for the task and be more willing to help. Note than one must **keep the list of reviewers short** for this to work.
3. **We'll leverage better tools:** We'll ditch that `#code-reviews` channel on Slack and promote the use of other tools like [Pull Reminders](https://pullreminders.com/) — a free _Slack_ integration that will keep in touch with every developer and make sure they follow up on their duties. In addition, using [GitHub's CODEOWNERS](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners) file in our projects will also help to streamline the process of _asking_ for Code Reviews in the first place.

It's **just three simple steps** but we expect them to have a high impact leading to _healthier reviews_, _happier developers_, and, in the end, _better software_. Sometimes things are not that complicated!

## 🚀 Collaboration doesn't stop on Code Reviews

While we've seen Code Reviews are incredibly useful, they're **not the one and only way to collaborate over code**. Sometimes you just need to do some pair programming - and that's an incredibly nice experience _when you really need it_! At Codegram, we particularly like **[Visual Studio Code's Live Share](https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare)** feature and we use it quite a lot. Damn, it looks like _Microsoft_ is killing it these days.

Finally, you should always keep in mind that everything said in this article **can't make up for missing documentation or bad architecture**. More than that — clean, documented code leads to **easier-to-deal-with** Code Reviews, and Code Reviews can help you **keep your code clean & documented**. Use that power for good!

<video src="https://www.codegram.com/blog/an-ode-to-code-reviews/yoda.mp4" autoplay loop muted></video><small>Did you seriously think there wouldn't be any Baby Yodas in this article?</small>

## 👋 That'll be all!

I hope you've enjoyed my humble views on the topic — with any luck it'll have inspired you to adopt some or all of these techniques and that'll help you and your team to be more collaborative. Or maybe you just think _this is bananas!_

In any case, I'd love to hear your feedback — you can send us an e-mail to [hello@codegram.com](mailto:hello@codegram.com), ping us on **Twitter** at [@codegram](https://twitter.com/codegram) or just yell at the programming gods!