Commit Description as a Thinking Tool

On top of this, it pays off to write the commit messages before the code

https://arialdomartini.github.io/pre-emptive-commit-comments

Writing is thinking in every situation, not just limited to commit messages. This is a fact that I'm concerned people are forgetting, or worse never understood to begin with.

I like git-notes (https://git-scm.com/docs/git-notes) for this sort of annotations and context. It's a nice balance - adjacent to commits, follows branch structure, easy to instrument, doesn't muddy the commit history.

Being able to stick a bit of directive text somewhere durable at any point in time has been surprisingly convenient for steering LLMs, as well.

I sometimes struggle to decide whether to put an explanation in a commit message, in the docs (say in an ADR). I tend to save everything as docs because files are a more “universal” interface, so to speak. They’re in plain sight and harder to miss.

I guess the main advantages of Git history are that it’s (1) uneditable and (2) directly linked to a specific commit.

Long ago I changed the default commit message to include headers “Why?” and “How?” to remind myself that I need to explain why a change is made (what this article focuses on), and how it is made (different implementation approaches considered). I followed this format for a long time. I was in the top 1% for commit message length at the company.

I use a different LLM family to review commits and write detailed descriptions. If a commit was written with Fable/Opus, I use Sol/Astra to write a well reasoned commit message. If the message doesn't match my intent, then that triggers a manual review.

This has been a topic belabored since commit messages were a thing. CVS? RCS? Probably earlier.

Tangential, but very early in my career, back when I was still using SVN at work, I used to write all my commits in either limerick or haiku, usually smuggling in some curse word(s) with some cheeky message in there. I was convinced that no one actually read them and I could get a laugh out of it.

I did this for months without anyone noticing, and eventually my manager schedules a very awkward meeting asking me why I wrote saying “cfquery fucking blows sometimes”. I had to sheepishly explain that I thought it was funny and then I stopped doing that and my commits became much more utilitarian and much less fun.

This problem has nothing to do with git.

The journaling of any iterative process requires clear notes that answer "why?" for each step. This is what will guide future maintenance.

Writing code faster than you can digest and explain it is at odds with this. You will incur runaway technical debt. This was already a problem long before the LLM era.

It is nice that more people are finally realizing this, but I'm still waiting for when we start speaking in generalities again and get over all the hype. Nothing ages writing faster than bringing up the specific tools.

[dead]