In my teenage coding days around 2001, before I used version control systems, and for a long time, I spent a lot of time reading code just to somewhat memorize it and to know what happens where and when and how I got there.

This state of mind has a distinct feeling for me, or rather: an aftertaste, that I instantly remember when I stare at a codebase that past me left with tons of dirty changes.

In a way, it’s a feeling of being lost and having no clue what’s going on, plus an embodied memory of soon having to fumble around.

I can also get this from brute force coding sessions where I touch one place, then another, and another, and just can’t find a good point to commit something as ‘working’. Just one more tweak, one more thing to try, one other place to change. Eventually, looking at the git status diff, I notice I can’t make sense of the changes anymore. That lands me in the same foreign territory where I feel lost and clueless and know I’ll need to fumble, even though I just have produced all these changes.

In normal, happy bouts of work, I have a story to tell. I changed X to do Y, and so Z had to be adjusted as well in one atomic commit.

When I feel lost and clueless, that’s usually the absence of a story. Even though I know why I did start this, and in which state of the system I stopped, I can’t retell the story of how to get there. That also means I’m not confident that the changeset is minimal, i.e. that this commit would only touch the places that needed touching and not more.

Kent Beck’s “Tidy First” principle to separate refactoring (behavior is the same, structure changes) from implementing a change comes to mind. I prefer that kind of separation. Then it’s easier to see what had to be done, and where.

With that approach, honest refactoring commits become 99% noise (e.g. mechanical renames) and 1% that’s worth looking at. They may not be trivial to review. But you get a lot of changed lines “for free” without having to reach every one.

If you mix this noisy refactoring work with actual changes, it becomes one muddy mess to look at. No joy for reviewers, either.

I wonder what this boils down to. I believe it’s the fact that it’s impossible to tell a linear story from after the fact that’s making me feel uncomfortable in situations like stale code changes or fumbling around for a day and leaving a mess behind. It’s impossible to tell the story of what needed to change to accommodate the new feature, and where the new feature is. It’s impossible to tell whether this is a minimal change at all, because there’s so much to look at.

Being a programmer, I also wonder whether git diff is the right tool for the job. It shows structural differences of a snapshot at the time of invokation; it does not take the process into account of how we got there. (Smaller git commits could have done that job, but by that point, that ship has sailed! So what do you do with the changeset you have?)

How do other people determine what makes a good commit, and what makes a cohesive change? And how many do actually care in their daily work?