Minimize the amount of changes in a changeset

When creating a new change set, always try to minimize the amount of changes it includes.

Do this by only modifying what needs to be modified to implement a feature or fix a bug. Keep formatting and refactoring changes for another commit.

The story of how I came to this practice

Many years ago I read Clean Code, a book I liked a lot. One of the things it discussed was to check in our code a little cleaner than when we checked it out. This meshed with the idea of continual improvement through refactoring which I was already following.

I took this principle to heart and made formatting changes, introduced constants, removed commented code and made small refactorings with my change sets. I kept big refactorings for different commits… well most of the time anyways…

Then later, on an open source project I contributed to, I was asked during code reviews to keep those changes out of the change sets. I was surprised since I thought I was improving the code’s quality. The reasoning was that the change set needed to include only the changes required to correct the bug that was addressed or implement the new feature we were working on. Refactorings should be kept as different endeavors or for instances where the code was being completely rewritten anyways.

Over time I started to see many cases in my own work where this made sense and eventually, after several years, started following this practice as well. One thing I like to do is keep notes of what changes I want to make, complete my work in a single commit and then make a separate commit for formatting and refactoring changes. If I don’t take notes, too often I forget all the little changes I wanted to do and never get around to doing them.

The why

When the commit needs to be read later on to understand the changes, revert them or when doing a blame/annotate to find out why a change was made it’s much easier if all the changes are related to the commit message and associated ticket number.  Otherwise you need to reason for each line if it was done in relation to the commit’s purpose or as a “bonus” refactoring.

Also, including unnecessary changes make for longer commits which make for longer code reviews. Both for traditional code reviews but also for yourself when you’re reviewing your changes before committing them (if you’re not doing this, this is a great practice everyone should adopt). In my experience the longer the review, the more chances some stuff will get glanced over.

Finally, every change we make, even when having a robust test suite risks introducing regressions. If you later find out your latest changes introduced a bug and it turns out it was in a refactoring, it’s much easier to revert or correct this refactoring without needing to revert a bug fix or remove a feature.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s