Blocked on code reviews? Let’s fix the process.

As an engineer at a growing startup, you’re moving fast and trying not to break things. Getting your code reviewed can be painful. You often have a very lean team of exceptional engineers, but they’re building the future along with you, and code reviews end up falling on the sidelines.

We faced this problem. We fixed it. Here’s what we did.

Photo by Alvaro Reyes on Unsplash

Where do I ask for a review?

Pain

“As an engineer, my threads on what I have to review, and what I have put in review are all over the place”

We are a remote-first team that uses Slack for communication. Requests for code reviews are often put in personal chats with other engineers or posted on common project-focused // team-focused channels. This creates a situation where conversations on code reviews are distributed across multiple slack channels and personal messages, and keeping track of what’s in review is difficult for both the engineer reviewing a pull request and for the engineer who’s blocked on a review to merge their changes.

Solution

We created a channel #backend-code-reviews on Slack. All requests for code reviews in the backend team are posted on this channel. The thread of any message is used for discussions on the changes.

Who should review my code?

Pain

“As an engineer, I don’t always have a clear answer to ‘who should review my code?’ in such situations, who do I request?”

This is a rare pain. In most situations, there is a clear code owner or project lead that can help with code reviews. But occasionally, you might make changes where pointing to someone as a default for code reviews is challenging.

Solution

We follow a policy of “use your best judgment”, empowered by GitHub’s reviewer suggestions — generated on the basis of file authors and modules’ owners. If there are no options (<5% cases), fall back to the on-call engineer.

How urgent is the code review?

Pain

“As a reviewer, I don’t know the priority of code that I need to review without having a discussion on its context. I often do not have time to discuss this context, and I end up incorrectly prioritizing what I need to review.”

As a reviewer, unless I am closely involved with the project or I take out the time to getcontext from the person who needs the review, I often do not know how urgent a pull request is. This urgency can range from — “needs to be deployed immediately” to “can wait for weeks, it’s an optional improvement”.

Solution

We follow a process of denoting this priority by colors. We use four colors:

🔴 : Code needs to be deployed immediately.
🟠 : Code needs to be deployed withing 24 hours.
🟡 : Code needs to be deployed withing the next 5 days.
🟢 : The required deployment timeline is longer than 5 days.

The end result

Building on everything we covered, a post on #backend-code-reviews can look like this:

@John Doe https://github.com/org/repo/<pull-request> 🟠
Adding an implementation to the report generator factory [one line description]
------
GitHub's Slack unfurl, which has comments and other information 
on the pull request's context.
------
--> threads --> discussion on the pull request // reminders if required

This simple approach has reduced our code review timelines significantly. Let me know what you think!