How to Request Changes During Code Review

A typical pattern among developers is that they want to be kind to one another, so they leave comments on pull requests (PRs) without explicit approval or requested changes.

But friends don’t let friends deploy bugs.

Contrary to the intent, leaving a “comment” is ambiguous and doesn’t indicate what needs to change.

Even though no one likes seeing the red “Requested Changes” text on a PR, getting a change request is better than making a fatal mistake.

Why It Is Hard to Request Changes

❌ Few people associate the colour red and the letter “X” with positive things. I think people have a gut instinct to think, “I don’t want to block this work, I have an opinion, but I also trust this developer to do what’s right.”

I’ve had to get over this feeling myself. “Request Changes” takes confidence, humility, and curiosity. I’ve shied away from requesting changes because of a lack of confidence in my suggestions.

How Request Changes

I have a formula I use for GitHub’s three options: Approve, Comment and Request Changes.

1. Approve: I will occasionally leave suggestions on PRs that I approve. I call out in my approval that the suggestions are not blockers, and the author can merge if they wish. However, if I have a suggestion that must be followed, I use “request changes.”
2. Comment: I rarely leave a comment. I don’t like this status because it is ambiguous. I understand that “Comment” is usually used to gain additional context before approving. If there is something I don’t know in a PR I will first take the time to learn about it myself. If I’m at a loss for understanding and need help, I will leave a comment review with the text: “I’m leaving this as a comment because…” and then explain what I need from the author.
3. Request Changes: I use this when I have clear changes I would like to see. When I use this review type, I always explain my request. I state “I am requesting changes because…” and outline the changes that should be made.

With that framework, I approach code review with a confidence that will give the author clarity on what I am asking of them, humility that will open conversation, and curiosity that will help us discover the best solution.

Confidence

This is the hard one. You need to be confident that you can articulate the changes you’re requesting and that your suggestions are grounded in your knowledge of the system.

This means you need to take the time to conduct a thorough code review. If you see something you are unsure about, don’t put the burden of proof on the PR author. Instead, take time to test the code out and understand it.

Confidence takes time, and with every code review you do, you will build up more confidence in your skills.

Humility

Confidence without humility is just bossy. The author might reply to your confident remarks with something you were unaware of. That’s okay! Code review is a conversation. Approach your comments with equal degrees of humility and certainty.

Curiosity

Sometimes things don’t make sense. I’ve written plenty of code where the reviewers need to come along on the journey with me to understand the change. Ironically, it’s always the one-line changes that take the most context to understand.

Approach reviewing code with curiosity and balance this curiosity with confidence. In the past, I’ve leaned too heavily into curiosity and asked a whole bunch of questions on a PR until my review was ambiguous.

Asking too many questions casts doubt on the work. Lean into confidence and ask questions that bring clarity to the code. If you are unsure about how the code works, pull the branch yourself and run it. Curiosity means learning the context in which this code was written, which helps the author propose the best possible changes.

Conclusion

Code review takes practice. Starting with a framework for each review type will help you decide when to use them. Then you can use code review as a conversation that refines.