Writing pull requests people actually enjoy reviewing

I can tell how a team feels about each other by looking at their pull requests. A 2,000 line PR with a description that just says fixes stuff is a small act of disrespect toward whoever has to review it. Writing better pull requests is one of the highest-leverage habits I have picked up, because it is the place where your work meets other people, and it is where good engineers quietly earn trust. A reviewer who enjoys your PRs will give you better reviews, faster.

Small is the whole game

If you take one thing from this, make it this: keep them small. A reviewer can hold maybe a few hundred lines in their head with real attention. Past that, they start skimming, and skimming is how bugs sail through. I would rather open four 150 line PRs than one 600 line PR, even though it is slightly more work for me, because each small one gets a genuine review instead of a rubber stamp.

Small PRs also fail safely. If a tight, focused change breaks something, you know exactly what did it and you can roll back without untangling five unrelated things. The giant PR that touches the database, the API, and the UI all at once is the one that gives everyone a bad night when it goes wrong.

Write the description for a tired human

The diff tells the reviewer what changed. It cannot tell them why, and why is the part they actually need. So I write the description for someone who is busy, slightly tired, and has no context loaded. I tell them what this does, why it was needed, and anything that will help them review faster.

• A one or two line summary of what changed and why, in plain language.
• Anything I am unsure about, called out directly so they know where to look hard.
• How I tested it, or how they can.
• Screenshots or a short clip if it touches the UI, because nobody wants to run your branch to see a button move.

That last bit about calling out my own uncertainty is something a lot of people skip out of ego. It is the opposite of weakness. Pointing the reviewer at the risky part means the review catches the real problems instead of bikeshedding a variable name while a logic bug slides by.

Make the commits tell a story

Inside the PR, I try to keep commits meaningful so the reviewer can step through my thinking rather than facing one giant blob. A commit that moves files, a commit that adds the new behavior, a commit that wires it up. When the history reads like a sequence of deliberate steps, a reviewer can follow the reasoning and trust the result. When it reads like wip, wip, fix, oops, they have no choice but to read the whole final diff cold.

I am not religious about perfect history. But the difference between writing better pull requests and writing frustrating ones often comes down to whether someone else can reconstruct what you were thinking without asking you in Slack.

Review your own PR first

Before I request a review, I read the entire diff myself as if I were the reviewer. This single habit catches more than anything else: the stray debug log, the commented-out block, the function I renamed everywhere except one place, the test I meant to write and forgot. Reviewers lose patience fast when they keep finding the obvious stuff you should have caught, and they start trusting your work less. Catch your own obvious mistakes and you spend their attention on things that actually need a second brain.

Reading your own diff also forces a useful question: would I understand this in six months. If the answer is no, that is a sign to add a comment explaining the non-obvious part, or to simplify the code so the comment is not needed.

Reviews are a conversation, not a verdict

How you respond to feedback shapes whether people want to review your work again. I assume good intent on every comment, even the blunt ones. If a reviewer is confused, that is real data: the code was unclear, and another reader will be confused too, so I fix the clarity instead of just defending myself in the thread. When I disagree, I explain my reasoning and stay open to being wrong, because I have been wrong plenty of times in exactly those threads.

Writing better pull requests is mostly about respect for the person on the other side. Make it small, make it clear, do the obvious checks yourself, and point them at the parts that matter. Do that consistently and reviews get faster, merges get cleaner, and your teammates start looking forward to your PRs instead of bracing for them.