Committing Changes to Your Codebase the Right Way

The difference between a good and a bad commit can be huge. It's no fun having to ask your colleague — or your past self — what a particular change was about, or what the current state of things is.

This article aims to provide a thorough guide to the best practices of software commits.

Why Bother?

If you’re already storing your projects on GitHub, you might assume the files are safe and that whenever you need to update code you'll pull the changes, and that’s enough. All of that might be true. But let's see what potential problems you can avoid by going the extra mile, and what additional benefits await if you do.

No Man Is an Island, Either in Teams or Individually

The reasoning above typically comes from a developer used to working alone. But the moment they need to share code with somebody else, we can expect that things are going to get messy and require a lot of explanation. Like, a lot.

Remember that our work doesn't end at just writing code. We also need to manage things, and that requires a degree of organization and methodology. And while working in teams more readily exposes the problems caused by poor organization, we can also benefit from a better approach when working by ourselves.

Atomic vs Bloated Commits

We've all needed to revert a small change and found ourselves looking for it in a massive commit that changes dozens of files and adds multiple features. How much easier would the rollback be if it was located in one commit that only addressed that specific issue?

The Messy, Bloated Way

git add *
git commit -m "new components"

In this example, we can bet that a large number of files are being affected. Additionally, the message "new components" doesn't tell us much of anything — such as what components, which functionality for those components, and if the functionality is new or a refactor. Also, are any existing bugs being addressed?

That information will be important when we need to change or recover something. We'll be trying to find a needle in a haystack, and we might just end up looking at the codebase instead and spending valuable time debugging while we're at it.

The Atomic Way

git add ui/login.html static/js/front-end.js
git commit -m "validate input fields for login"

Now we're getting somewhere, as we start to have a clearer idea of what's going on with that one commit.

The trick is that we can semi-automatically commit changes as part of our workflow. That is, doing a block of work that does something very specific (implementing particular functionality, fixing a bug, optimizing an algorithm), testing (and write a unit test, if need be), adding a description while our memories are fresh, and committing right away. Rinse and repeat.

The Structure of a Good Commit

These rules aren't carved in stone, but can help you estimate what a good commit might look like:

• unambiguous: no second guessing about what those changes do.
• insightful: clearly describing what the code does, even providing links or extra information when necessary, and marking the bugs or issues that are being addressed.
• atomic: addressing one single thing at the time (think of a "block of work", which could be anything from 20min to 2h, or even 2min if it was a quick bugfix).

Let's look at a template and break it down:

The post Committing Changes to Your Codebase the Right Way appeared first on SitePoint.