My pre-commit routine ✅

I have a set of loose rules that I always¹ follow when I commit code to version control.

The idea is that we can accept somewhat sloppy code while we are actively working on it. But whenever we commit code to the repository, we ensure that the code we commit is high-quality by systematically improving layout, documentation, tests, and other aspects of the modified code.

It is an example of a small and simple routine that can give large long-time results.

The steps of the routine #

Before checking in, I look at the diff to be committed and go through the following steps.

• Update from main
  • Ensure you are working against the most recent code
  • Resolve any conflicts
• Clean up and refactor
  • Run formatters and linters and fix any issues
  • Take care of remaining TODO comments
  • Perform necessary refactoring
    • In particular, look for duplication and opportunities to split large functions.
  • Improve code structure and layout
    • Are individual functions easy to understand?
    • Are related parts of the code on the same level of abstraction?
    • Does the order of functions, variables, etc help make the file readable?
    • Does the abstractions used communicate intent effectively to the reader?
• Document and comment
  • Document public interface
    • Ensure parts of the code that other people will likely interact with is documented unless completely trivial. Otherwise you will likely curse yourself in six months time when having to look at the code again.
    • Documenting it is also a good way to ensure you know what it does and that it actually makes sense.
  • Comment to make it even better
    • A few well placed comments here and there can make all the difference. Focus on why and putting things in context, rather than describing what the code does.
• Add and run tests
  • Add tests if necessary
    • Are the changes covered by relevant tests?
    • If the change is a bug fix, is there a test to ensure it does not reappear?
  • Verify that all tests passes
• Careful inspection
  • Are all changes in the commit necessary?
    • Can I revert some changes that were made along the way but are no longer necessary?
  • Perform a “personal code review” of the commit, especially changes

When you feel satisfied with quality of the code, go ahead and commit (providing a good commit message of course).

Rationale #

Performing this routine before committing is a trade-off between two extremes; keeping the code we’re modifying completely tidy at all times, and cleaning up/documenting everything at the end of the project. With the first alternative we might do a bit too much work in vain. On the other hand, the latter alternative almost guarantees that we will do all work in vain.  

We need to find a middle ground where we do it often enough, but not too often. Doing it prior to committing is a good alternative because:

• Cleaning up and documenting gets done.
• The quality of the checked-in code is high.
• It won’t feel like a gigantic task, as it only involves a couple of files.
• We don’t have to do work just to redo it again a few seconds later, while modifying the code.

For developers used to a feature branch workflow, it may feel natural to do cleanup when the feature is done. Unless the feature is very small, I would argue that is too late. The amount of work has often become large enough that the cleanup will feel too large and thus not performed as thoroughly (if at all).

I should say however, that I do make exceptions from the routine every now and then.

What is your “pre-commit routine”?