An Ode to Code Reviews

At Codegram, 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, GitLab's 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 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!

Code Review all the things!

...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 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 or Netlify's Deploy Previews 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.

Coding alone with a blanket at night

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 — 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 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 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!

Did you seriously think there wouldn't be any Baby Yodas in this article?

👋 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, ping us on Twitter at @codegram or just yell at the programming gods!