Code Messy, Commit Clean

Posted On: 2022-05-30

By Mark

Today's post will be about a coding habit I've developed. While working with others on a project, I always try to keep my code commits small, tidy, and focused. Importantly, this is an intentional choice: regardless of how much of a mess my (digital) workspace is, when it's time to commit I thoroughly scrub it down. From the outside, this practice might look like a waste of time*, but it's one that I've developed in an effort to optimize my (and my team's) productivity in the long-run, and I think it's been rather successful.

Brief Background on Commits

Most modern software developed by a team uses some form of version control (ie. Git). In general, version control systems allow multiple team members to work on the same file(s) at the same time, with no delays or conflicts*. When a team member is ready to share their work, they "commit" the change - often by pushing it to a remote repository. Team members can then acquire these changes for themselves - a process that often involves performing (tool-assisted) merges between their in-progress work and any new code from the teammate. In large or particularly active teams, this final step will occur quite a lot**, and it's the primary reason why version control systems are so valuable for teams.

What is Tidy?

Tidy code commits only include relevant changes. This may seem obvious, but it actually requires a surprising amount of rigor - from the leftover code of previous attempts, to accidental whitespace changes (tabs versus spaces), to automated systems changing files without notice. By the time a developer's finished even a modest sized task, their workspace can be quite cluttered with unrelated changes. Tidying up, therefore, becomes an excercise in removing the unnecessary and excluding things that are only useful on the developer's machine (ie. local configuration files.)

Tidy for Yourself

The simple, selfish reason to keep commits tidy is that it's easier to do a merge. Any reasonable source control will require that you resolve merges before you commit, and thus committing messy code often leads to trying to merge messy code. This can be exacerbated when other teammates commit their own messy code: it's harder to merge a dozen changes that don't make sense than only one or two.

Tidy for Others

Team size is a force multiplier for merge issues. Where messy commits might cause occasional merge-related bugs, in a large team the odds of a bad merge - and the bad merge causing problems later - goes up dramatically. Nobody likes merging*, so keeping tidy commits is a kindness to the whole team, improving productivity and mood by minimizing a source of loathing.

Tidy for the Future

Most version control software lets users view the history of changes and/or files, making it possible to compare past versions or discover when a bug was first introduced even years after the fact. Using history in this way can be tricky/time-consuming, largely depending on how tidy the commits themselves are. Keeping the changes focused and having clear messages on commits are key for making history user-friendly, and it can mean the difference between spending days sifting through unrelated changes versus immediately identifying the cause of the issue.

Conclusion

Hopefully it's now clear why I developed the habit of tidying up my commits - and why I think it's valuable. If you're in a position where you use source control (for programming or even other tasks), I hope you'll choose to do the same. After all, if everyone made tidy commits, teams would be more productive, their software would have fewer bugs, and everyone would be a bit happier.