Micro refactoring series — Crafting a changeset

When working on features and bugs, developers tend to go deep into the code and often make many changes in one go. It’s usually harmless, but if you mix a lot of unrelated changes, it becomes problematic for the PR reviewer. In many cases, it may end up in an LGTM (Looks good to me) comment, and 💥 right there — you let a potentially sub-par code get into the system.

In my post last week, I highlighted how writing clean, easy-to-understand code is a beautiful gesture toward your fellow developers. Today I want to extend that idea to git commits, aka Changeset. And it starts with you!

Assuming you were to review a PR — What is it that would make your life easier?

Your story is different from mine. I would safely assume we share a common trait: we don’t want to overspend our energy. We have limited stock.

So how do you write a Changeset that is easy on the reviewer’s eyes?

Group similar changes together

As a developer, you want to beautify the code format. Maybe you want to rename functions and variables or make trivial code restructuring. It’s not a change that needs someone’s special attention. How do you let your reviewer know that? Put it in a separate commit.

Don’t group your logical changes with cosmetic changes.

Commit often; commit small.

I know you two weren’t pair programming (if you were, why are they reviewing your PR?). How do you let your reviewer know how to follow code changes? What was your thought process behind that change anyway? You give them a huge pile of code to go through. Where does the reviewer start? No — an alphabetically sorted list of files shown in the PR review tool is not the correct answer. You have to let them know where to begin with — for real.

You make several small commits. Commits that tell bite-size stories, revealing your thought process, named with your commit messages. Now that’s a real help. You are walking your reviewer down memory lane! That’s a beautiful gesture. It’s hard — but it’s true love. Surely your PR reviewer appreciates this act.

Make small bite-sized changes. You are telling a story. Make sure it’s beautiful.

Showcase your work

Now that you are a great colleague, go that extra mile and attach a demo of your work. Screenshots, gifs, videos, logs, test runs, anything, really! It helps your reviewer connect the dots.