Segregate your code commits into tiny topical changes.

February 15th, 2014

If your not using source control for your coding projects, get off my lawn. :P (#JustHadToSayIt)

Now that I’m only reaching people who use source control (serious developers), I’d like to ask that you focus hard to only commit changes that belong to a single topic at a time. Think SRP for code commits/check-ins.

What is a topical commit?

That almost looks like ‘tropical’ and wouldn’t it be nice to be in a tropical place doing commits to your code, but I digress…

The topics I’m referring to are specific functional units of change where each tiny commit is related to a single topic or theme.

For example:

  • adding feature X
  • refactoring
  • bug fix
  • spelling fix
  • Updating comments/documentation
  • *** code formatting ***

I highlighted that last one for a reason as it’s the impetus for writing this post.

Don’t mix topics/themes within a single commit!

Instead break them into multiple commits. If you’re using git, checkout ‘git add -p

If you have a one line bug fix but the file has 20 lines of code formatting changes (you know who you are). It makes determining what the bug fix is nearly impossible from the changes that are code formatting.

Using tools like git bisect to look at history become difficult. Pull Requests in GitHub become difficult to understand. If you’ve left a codebase for a while and come back, try reading changes that have happened over time to get caught up can be extremely difficult to do if your commits are not topically based.

Let’s just NOT mix topics in our commits, ok?

K, THX bye!

Happy Coding!

  • AlSki

    I have to agree with this, however when you work in a more reasonable sized team there can be an issue producing commits that provide a meaningful unit of change as delivering on a different magnitude of pace to everyone else, can lead to friction. Producing a constant stream of commits can overload your continuous build system and your colleagues will never have the chance to complete a commit without first updating (depending on which VCS you are using).
    Since my industry is still using SVN, I’ve found that running a local copy of Hg (you could use git instead) gives you an opportunity to perform as many micro commits as you like, and only when you are ready to affect everyone else, then start transferring those commits to the team VCS. Even then I tend to separate my changes backed with a JIRA, from my “Resharper + Stylecop” commits. If nothing else when my colleagues run “Annotate” it gives me a chance to duck the blame :-)

  • odalet

    Well… A useful reminder for myself. As you say, I know who I am, and though I know this is bad, I can’t prevent myself from reformatting/refactoring even while bugfixing. Bad bad bad.