Published on

Writing Pull Requests That Actually Get Reviewed

Authors

Code review is the primary quality gate in most software teams. But the bottleneck is rarely the reviewer's time, it's usually the quality of the PR itself. I've seen good code sit unmerged for days because the PR made it hard to understand, and I've seen mediocre code get approved quickly because the author made the reviewer's job easy.

Here's what makes the difference.

Size

The single most impactful thing you can do is keep PRs small. Reviewers can hold a small diff in their head. With a large one, they can't, so they either approve without really understanding it or leave it sitting in the queue.

A PR that touches one thing is almost always reviewable on the same day. A PR that touches eight things might sit for a week.

If you find yourself writing a big PR, look for seams you can split on:

  • Refactoring separate from behavior changes: extract the rename/restructure as a standalone PR. Reviewers can approve structural changes quickly when they don't have to also understand the new behavior.
  • Tests separate from implementation: sometimes it makes sense to land the tests (or stubs) first
  • Infrastructure separate from features: adding a new database column is different from the feature that uses it

The Description Is Not Optional

A PR description should answer: what changed, and why?

## What
Replace the in-memory session store with Redis to allow horizontal scaling.

## Why
The current implementation stores sessions in the Node.js process memory.
This means users get logged out on every deploy and sessions don't persist
across multiple instances. The team is planning to run 3 instances in production
next quarter.

## Notes for reviewers
- I left the in-memory store in place behind a feature flag (`USE_REDIS_SESSIONS`)
  so we can roll back quickly if needed
- The Redis client config is in `src/config/redis.ts`
- I added integration tests in `tests/session.integration.test.ts`, these require
  a running Redis instance, so they're skipped in CI by default

Notice the "Notes for reviewers" section. This is where you do the reviewer's job for them, you've already read the code, so tell them where to focus, what's intentional, and what's a tradeoff you made consciously.

Explain Tradeoffs You Made

Every non-trivial implementation involves decisions. Write them down:

  • "I chose X over Y because Z"
  • "I know this looks like it could be done differently, but the existing architecture requires this approach because..."
  • "This is deliberately kept simple for now, the follow-up issue is #456"

This does two things: it saves the reviewer from asking the same questions you already answered, and it demonstrates that you've thought carefully about the problem.

Leave Your Own Comments

Walk through your diff before you submit and leave comments on parts that need context:

  • Complex logic that isn't self-explanatory
  • Workarounds for weird edge cases
  • "This looks wrong but it's actually correct because..."

Leaving your own comments is not a sign of weakness, it's a sign that you've thought about your code from the reviewer's perspective.

Make the Scope Clear

Reviewers should know what's in scope and what isn't. If you've touched something adjacent but chose not to clean it up, say so:

"I noticed the error handling in userService.ts is inconsistent, but I left it alone to keep this PR focused. Happy to do a follow-up cleanup if that's useful."

This prevents reviewers from asking "why didn't you also fix X?" when X is something you consciously decided not to change.

After the Review

  • Respond to every comment, even if it's just "done" or "good catch"
  • If you disagree with a suggestion, explain why, don't just silently not make the change
  • Re-request review explicitly after making changes; don't assume your reviewer will notice

The Underlying Principle

A PR description is communication. You're trying to help another engineer understand a change they didn't write. The more work you do to make that easy, the faster your code ships, the more your teammates trust your judgment, and the better the feedback you get.

Reviewers approve the code that's easy to review. Make yours easy.