Requesting a review means wrangling reviewers

Problems with lack of reviewer engagement

A conversation from countless retro meetings: “I want to introduce some mechanism to get folks to look at my PR/MR/CRs.” Perhaps that looks like having aggressive automatic notifications; perhaps that looks like having reviewers pinky promise to look at all reviews assigned to them within $TIME_PERIOD. Approaches vary.

Let’s be good engineers and move deeper, past the XY nature of the problem¹. Why do they want a mechanism? “Because I’m having a hard time getting reviews looked at”. Why are they having a hard time getting reviews looked at? Here, the answer varies.

Perhaps this is a universal problem: everyone on the team is having a hard time getting reviews looked at. This can be a matter of capacity. The team’s not planning for enough time on the review cycle. Adding aggressive reminders will only annoy already overloaded individuals; instead, the team needs to have a conversation about work allocations with their manager.

More often than not, however, it’s individual. There are one or two team members who consistently have issues getting changes reviewed. The senior dev never seems available; they publish changes and those sit there, unacknowledged.

At this point, the question shifts.

How did you communicate with your reviewers?

I published a PR/MR/CR.

What did your reviewers say in response to it?

I didn’t hear anything back.

How do you know your reviewer saw the change and knows its priority?

Well, [GitHub/GitLab/internal tool] sent them an email.

Reviewers are busy

Now of course there are exceptions, and we’re absolutely grateful for those saints, but most reviewers don’t sit around watching their emails like, “Oh boy! When will I get to review another change?”. They have interviews, meetings, and work of their own they’re trying to push through. They might not even see their “Noisy Notifications from GitHub” folder on a given day.

This gets worse with seniority. When I was an SDE II, I’d sit on reviews for just my team. There’d be at most five or so reviews open for my eyes at a given time. By the time I left AWS, it was common for me to be tagged on around twenty-five open reviews at a time. And these are code reviews. This isn’t even counting design reviews, which likewise grow in volume with seniority.

So. The reviewers who likely will have the most feedback for a given change are also the most time constrained.

Explicitly communicating requests creates better review outcomes

Imagine that senior engineer who has one hour to look at reviews today, opens up $CODE_REVIEW_TOOL and sees twenty-five open reviews. They really need them to look at your review – it relates to a system they designed and you have questions. They’re about to ignore twenty-two out of the twenty-five open reviews. How do we shift the odds to be in your favor?

The very simple answer: ask them.

It is polite and professional to send a message that looks like, “Hey Stephanie, I was hoping to get your review on $LINK_TO_CHANGE. I’m trying to get this in by EOD tomorrow. This is important because of $REASONS. Can I get your eyes on before then?”. Stephanie now knows you’re counting on her; she’ll glance at the change description, see its relevance and importance, and see that yes, she wants to work that change in. And she’ll let you know.

Or, maybe Stephanie really doesn’t have capacity. In that case, she’ll tell you that she’s unable. Which allows you to find a contingency now rather than two days of frustrated waiting later.

Nothing bad will happen from explicitly communicating with your reviewer ahead of time about scope, structure, priority, etc. This makes your reviewer’s job easy. This is a way of minimizing burden on them.

Explicitly communicating opens doors. If I tell a reviewer, “Hey, I’d like you to take a look at this by 3pm” and they say, “I don’t have time”, often there’s still room for negotiation. I can spend two minutes briefing them about points that I anticipate objections on. I can ask them to just look at one function. They can bring up that another reviewer would be well-suited to look at the change. None of these options would be available to us without explicit communication about expectations. All of these options are better than me waiting in silence, and all of these options lead to better outcomes for our team.

Explicitly communicating when reviewers “ghost” is polite

A reviewer’s agreed to look at a review by EOD, and that time has come and gone. Here, again, I recommend explicitly communicating with the reviewer. It’s polite and respectful to say, “Hey Stephanie, I was hoping to get you to look at $LINK_TO_REVIEW. Do you still have time to take a look?”. Chances are they’ve forgotten and will be grateful for the reminder.

Here, the trick is to remain explicit. Posting on a general team channel, “$LINK_TO_REVIEW is still open”, for instance does not tell Stephanie a) you’re waiting on her specifically b) you’re blocked c) this is time-sensitive. Direct communication – DMs or tagging reviewers and including information on scope and urgency – gives reviewers the information they need to prioritize the review.

Involving reviewers upstream saves time

The best outcomes occur when the review is a continuation of a conversation. When the reviewer has helped shape the artifact step by step and knows pretty well what’s coming down the pike. Most of the really bad reviews I’ve ever seen (the “sending this back to the drawing board” kind of ones) are because the reviews have been “ambush reviews”, where the reviewer hasn’t been involved in or aware of the upstream ideation.

I’d suggest asking, “How can I get my reviewers involved upstream in a way that respects their time?”. One way is to grab ten minutes of their time early on to run a couple of ideas by them in front of a whiteboard. Other options include sending them a basic sketch of a diagram or database schema which helps them see where your head is at. What we’re aiming for: terse communication that’s information-dense and easily consumable in ten minutes or less.

The net result: my reviewer shaped the final output of the work. They had a say in the overall approach, so by the time we get to looking at code, there are no surprises².

This doesn’t take much time at all. Even a very small five-minute informal conversation suffices. If your thoughts are fully and completely formulated, it might be a sign that you’ve waited too late to involve reviewers. I strongly prefer to involve reviewers once I have my head wrapped ~60–80% of the way around the problem. I can get that ~60-80% very quickly, often in a couple hours. Having invested minimal time and with strong jumping-off proposals, I come prepared, which respects my reviewer and gives them a chance to contribute insight that can completely alter the course of the work before I’m overcommitted.

Closing thoughts

Explicit communication around expectations and sharing where your head’s at early and often is one of the best ways to build trust with your team. Not only does it lead to reviews being shipped quickly (the proximate issue), but it makes it fun to work on that team. It feels exciting to ship reviews quickly! It builds connection with team members, inviting them into the decision-making process. It helps the team make better choices (and again, quickly). It helps create an environment in which team members feel included and like they belong. All of which I want for my team, and I hope you do too.

---

Appendix: example communication

If I’m working on a medium-sized non-controversial change, here’s what my communication might look like over the course of ~3 days:

Day 1

1. Let folks know in standup that I’ve started thinking about a particular problem, highlighting points of ambiguity.
2. Grab a couple of co-workers for 10 minutes to try to figure out why the approach I like is actually bad.
3. Start writing up a little doc or summary (with pictures!) that captures that discussion. Post about progress before heading out.

Day 2

1. Finish writing little doc. Add subsequent shower thoughts. Post a brief summary with link to the doc on Slack.
2. Announce in standup: I’m going with whichever chosen option.
3. Implementation, again immediately post on Slack
   • when I become blocked
   • about items I find surprising
   • if it’s been more than half a day from folks hearing from me

Day 3

1. Post first PR, assign a couple of reviewers.
2. Ping those reviewers on Slack, saying that a change is ready for their eyes.

Day 3 continued, Day 4+

Continue implementation; communicate blockers or surprises.

That’s around three or more touchpoints with reviewers per day, throughout the course of development. These do not add burden to the reviewer. Of these, all except one were either async look-at-Slack-whenever type updates or were in standup. The one exception was the “let’s draw on a whiteboard” session, but those are fun so that doesn’t count.