Growing up, I loved watching Looney Tunes. The ever memorable Road Runner outsmarting Wiley Coyote.
I don’t know if I’m conjuring an episode, but I have memories of Wiley Coyote standing in the desert, with a bomb dropping on him. He raises up an umbrella and the bomb explodes. When the dust and smoke settles, Wiley Coyote is standing on a small pillar of earth which juts up from the center of the bomb’s crater.
I often think of that scene. The bomb is something that Wiley Coyote tried to use against the Road Runner. And the consequences are that he’s battered and bruised and standing on a pillar of earth, all alone, distant from the edges of the crater.
I’ve found that when I submit a Pull Request (PR 📖), I sometimes think of myself as standing on a pillar of earth at the center of a crater, clutching an umbrella and hoping it doesn’t all fall apart.
My fellow code reviewers stand around the crater’s edge looking in at me. Some reviewers are quite far away others are rather close. Those far away may not be equipped nor prepared to engage with the PR. Those closer are the ones better equipped and/or prepared.
I know that someone further away from where I’m at may find it harder to help me. Maybe my code is too abstract, opaque, or convoluted for them to understand. Maybe I’ve introduced patterns and concepts that are unfamiliar.
The process of collectively submitting and reviewing a PR is the work of filling in that crater. “Closing the knowledge gap”, if you will.
And as folks review and engage in PRs they begin to build context:
- Of the code-base
- The idioms of the contributor
- Vocabulary used to talk about the project
That shared knowledge helps lighten the teams load; creating a stronger lattice of knowledge.
And here’s something I encourage: review PRs outside of your domain of knowledge. That means being curious and asking for clarification. Encourage folks to fold those clarifications into the code and/or commit history. Conversations in someone else’s User Interface (UI 📖) are ephemeral and likely lost. Consider your conversations and what might make sense to fold back into your code-base. See Commit Messages Do Matter for more on this.
Also remember that folks putting forward a PR are putting forward a little bit of themselves for scrutiny. Hold that as something sacred. Consider open ended non-emotionally charged questions.
- “I’m not following what’s happening here, could you explain it?”
- “I think I’m following what’s happening here, but wondering if you considered this other method?”
- “I’m a bit confused about the expected output, could you write another spec to clarify?”
- “I see this number or string used a few times, what could we name that?”
Ultimately, be curious and cheer for the contributor. Help them get the code merged. And also, don’t allow perfect to be the standard. You can say “I think there might be an edge-case here, but let’s file a bug and merge this code. Then we can tackle the edge-case if the team thinks it is important.”