How to Make Your Code Changes Easier to Review?

Quick Tips for Efficient, Team-Friendly Coding in < 2 min and 400 Words

Making easy-to-review pull requests is key to faster and better teamwork.

Great PRs let more people chime in with quality feedback.

Good changes create faster review cycles and uncover potential bugs earlier.

They make you sleep better at night by not worrying about that +2k line diff someone slapped LGTM on and got automerged into prod on Friday night. 🧘

In this article, you’ll learn How to create code changes that are easy to review.

Note: I use the terms diff, Code Change, PR, and Pull Request interchangeably. They all mean the same thing: getting changes from Branch A to Branch B.

1. Size

Small PRs are a delight to look at.

They have a ton of benefits, they

• are reviewed faster,

• contain fewer bugs,

• leave less space for doubt, thus

• require less back-and-forth

2. Context

Keep related changes together.

What’s easier to review:

1. a PR with 250 files where in each file, I removed the same repeated comment from line 1 or

2. a PR where I fixed a bug in our payment process that sent the wrong product to Stripe, but I also did 1. in some of the files

To me, 1. is the way to go for two reasons:

1. Once you see the pattern, your brain will be faster at scanning the PR. Mine does nothing but look for that red line at the top of each file. 🤪

2. No double work in case of a revert. It’s super annoying to revert a PR that had a fix for two different things, and one of those things actually worked, but the other flopped.

3. Guidance

Ok. Sometimes, you’ll have those PRs where connecting the dots is harder. But it doesn’t have to be for the reviewer!

I run into a deleted line that seemingly has nothing to do with the goal of the PR. I’m forced to do one of these:

1. leave a draft comment I eventually return to when I figure out where the line moved

2. ask the author

None of these sound ideal.

Instead of letting people figure out some of the unexpected changes, I leave comments on the not-so-trivial ones:

In this PR, I moved some filtering logic in the React component tree into a component up in the tree.

When you look through a long list of changed files in GitHub from top to bottom, such changes are harder to spot.

---

These were my tips for creating PRs that are easier to review!

What’s the code review culture in your organization?

Do you get a lot of LGTM approvals?

📰 Weekly shoutout

1. How to lead projects from start to finish as a software engineer in this guide

   Jordan Cutler
   shows you how to start and finish projects as a software engineer working in an organization.

2. You are firing people too late – Running my business puts me in the first line of defense and taught me some lessons in decision-making. Firing people is one of those decisions, great article from

   Anton Zaides
   .

3. The Ultimate Guide to Writing an Engineering Newsletter (Part 1) – Can I also write about my experiences? Is there any value in that? Of course! Read this great guide

   Nicola Ballotta
   and start your engineering newsletter today!

📣 Share

There’s no easier way to help this newsletter grow than by sharing it with the world. If you liked it, found something helpful, or you know someone who knows someone to whom this could be helpful, share it:

🏆 Subscribe

Actually, there’s one easier thing you can do to grow and help grow: subscribe to this newsletter. I’ll keep putting in the work and distilling what I learn/learned as a software engineer/consultant. Simply sign up here: