Embrace Request Changes

Peer review can be difficult both for the reviewer and the author. It can be easy to become defensive about perceived negative feedback, especially if you’ve put a lot of thought into the work before submitting it for peer review. Seeing that big red X is a good sign that something is not as clear as it can be, and it can be a good conversation starter for collaborating on how the work can be more readable.

As a software developer part of my day is to request peer review from others on my work. Our company uses Github to review others' work. In this process, reviewers can approve or request changes. Think back to the primary school years with the giant red Xs or green checkmarks.

At my company, there have been good ideas on using Github’s peer-review request change feature. I’ll briefly go over what I took from those talks and how I apply them to my own workflow via a list of myths.

Myth #1 You done f*k’d up!

False. Request changes is a tool to start a conversation. As the reviewer uses this to offer suggestions, change requests are a great way to start a conversation and share knowledge. To make the most of this feature, keep your suggestions succinct. The author has likely put a lot of time into weighing options before deciding on implementation.

As the author, do not feel bad; in contrast, feel good. Request changes are a conversation starter. Reach out to understand what is being requested and why. As the author, this is an opportunity to learn or teach, and by embracing these opportunities, you become a better developer (or writer, researcher, better at your profession…).

Myth #2 Requested changes must be done

False. Request changes are suggestions and a conversation starter. In some cases, the suggestions provided may be misinformed. You, the author, are now in a position to share knowledge with the reviewers, thus making everyone better. Development (or research, or your profession) isn’t a solo endeavour, and embracing conversations initiated via requested changes feeds into a culture of collaborative learning.

Myth #3 You should avoid getting request changes

False. Well… no not false… so true?

Why not both!

While it’d be great to never need to make changes to your work, this isn’t realistic. Sure, you could spend additional time perfecting your work, but it’s often better to get a peer review earlier.

This encourages learning by letting you fail fast. If you wait too long to share your work, you’re likely to end up with larger bodies of work, making the work much harder to review. Smaller changes — and changes that are easier to understand to be reviewed — are less likely to have reviewers request changes. Breaking up larger changes into many works to be reviewed is likely to encourage more engagement from your peers. Sharing your work for review early and having those reviewers input early also helps to have that feedback loop.

One of the fastest ways I learn is by failing fast and receiving change requests on my work. This doesn’t mean I intentionally write code that needs changes, but when I do have changes requested, those requests are handled early enough that I have time to pivot, learn, or teach.

Myth #4 It means you are a bad coder

False. Absolutely not true! I think GitHub should actually change the colour from red to blue. Think about driving a car. Request changes are not slamming on the brakes because something bad will happen if you don’t. Don’t try that on a highway; I do not recommend that. Instead, think of it as the navigator starting a conversation.

Reviewer (passenger): “Oh hey, I think we need to turn here. Yes, this is our turn.”

Possible responses:

Author (driver): “Oh you are right! Thanks!”

Author (driver): “Ah I don’t think so! See, we want the next one.”

Reviewer (passenger): “Oh yeah, you are right!”

Author (driver): “Oh you are right! But it is too late. Is it okay if we take a detour and turn around up ahead?”

Reviewer (passenger): “For sure! That sounds like a good plan.”

Author (driver): **no conversation, doesn’t look at the passenger, randomly slams on the cars break and get mauled by a semi that was trailing them**

Let’s not get mauled by semis.

Recap

Any form of constructive feedback like Github’s “request changes” feature on work is a tool simply used to teach and learn by encouraging conversations. For code, request changes can be used to help keep our systems easy to read or prevent something bad from happening (but it is not slamming on the breaks, more just preventing code from being shipped). Both the reviewer and the author are in a position to teach and learn. It is not always the reviewer requesting changes who teaches.