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.

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.