Why I still hand write my commit messages
29 points by JamieTanna
29 points by JamieTanna
Even in the projects I run, I don't enforce this on anyone - I've learned over the years it's not worth it to try and require it - and although I'm happy spending the time doing it, not everyone is as interested.
I don't maintain any large open-source projects, nor am I in a strictly management role at my company, so I admit I don't have as much experience here but I would certainly take a stronger stance on this if I was in a position to.
Getting an LLM to write code is one thing but offloading the reasoning behind the code and communication of the change is something I really feel like we can't give up or allow to degrade. If we aren't going to code anymore, then what exactly are we going to do, if not take the time to communicate our own ideas with our own voice? Anyone seriously pushing heavy LLM usage in software development loses all credibility if they try to simultaneously say "taste, design, and understanding still matter" while also using LLMs to write.
I deeply appreciate Oxide's position [0] on this:
If, however, prose is LLM-generated, this social contract becomes ripped up: a reader cannot assume that the writer understands their ideas because they might not so much have read the product of the LLM that they tasked to write it. If one is lucky, these are LLM hallucinations: obviously wrong and quickly discarded. If one is unlucky, however, it will be a kind of LLM-induced cognitive dissonance: a puzzle in which pieces don’t fit because there is in fact no puzzle at all. This can leave a reader frustrated: why should they spend more time reading prose than the writer spent writing it?
[0] https://rfd.shared.oxide.computer/rfd/0576#_llms_as_writers
(Author here)
I would certainly take a stronger stance on this if I was in a position to.
I would also like to 😅 Unfortunately, I've had that battle before, and it wasn't something I could really get to uniform acceptance of the benefits.
I'd exerted my influence and coached a lot of the team to writing much better commits, to the point I was pretty happy generally with how things were going, it did end up being another roadblock to getting things done, and I did have some grumbles of "the code is good, CI is happy, I've got approving reviews, but you want me to add some text to the commit message"?
It's pretty fair, and in my linked post I talk about it a bit more tongue-in-cheek, but it's one of those things that I think is hard to really get everyone to consensus on.
It's also the sort of thing that i.e. if you're close to sprint end, or in the middle of an incident, you're not necessarily going to write the best commit message. They're more extreme examples, yes, but I feel like folks are more often in a "time crunch" than they're happy and chilling, and free to write nice text, especially if they're less practiced writers.
(I've spent my whole day re-writing the same ~12 gnarly commits, and it's something that I value as a good use of my time, but not everyone sees it that way unfortunately)
Getting an LLM [...] offloading the reasoning behind the code and communication of the change is something I really feel like we can't give up or allow to degrade.
I agree - and if I'm honest, I'd sometimes prefer no commit message to something AI generated at that point, if there's no explanation of the intent behind the change.
Getting an LLM to write code is one thing but offloading the reasoning behind the code and communication of the change is something I really feel like we can't give up or allow to degrade
Offloading the reasoning is the selling point. The bottleneck for producing software is the time spent reasoning, and building the theory that it takes you to get to understanding.
I don’t know how many times I’ve reworked or completely thrown away a commit and started again, because of things that I realised while writing the commit message; but it’s more than a few. I write 10–30 line messages very frequently (and have gone past 100 on occasion).
I encourage others to write long commit messages, but I don’t think I’ve ever really convinced anyone, at least not to my degree.
The best fun is fifty or more lines explaining a single-character change.
Today I've spent most of the day converting what was ~7 commits to ~12, as each time I was reviewing the diff and writing the commit message, I found more things that I either wanted to split out, or thought "wait, that can't be right..."
Sometimes you (or someone else) will catch in a code review, but IMO, it's much better to do some of that work up front!
I struggle to see the point of writing any commit message if you're not going to hand write it, what are you storing that I couldn't re-deduce with my own LLM?
I suppose the LLM could encode notes from your conversation that are only available in its context? Seems like a stretch.
I think I often sit on this weird fence too - like... if you're going to assume the LLM is good enough to not only write but architect a lot of your PR and commits, why not go whole hog and have it do the messages too?
Contrapositive to that, even writing a little bit of your own code (which is often what you end up having to do at the end of the day even in a reality of a cyberfuture of LLM tools working all the time, perfectly)... you're gonna want to actually write down what you did more than the LLM did - because the commit message is one of the few artifacts that is encoding what you did in human language over programming languages.
I hand-write all my commit messages, but if someone thinks LLM-generated messages are good enough, I see plenty of reasons for them to store generated messages in their associated Git commits.
git log and IDE plugins generally don’t have an extension point to display an LLM-generated message in the log instead of the one in Git’s database.Also, I bet there are some people who generally accept LLM-generated commit messages but would stop and edit the message if the subject line were obviously wrong. For those people, saving the generated description in the message records that a human has skimmed and approved the subject line, which is better than no information.
Much of this assumes that an LLM generated message has a purpose to exist such that it can be displayed or logged, over and above the diff itself.
I suppose generating a header and brief description for caching purposes makes some sense, assuming that simply feeding an LLM the diffs is overly expensive in terms of reasoning about what they're for, although I'm not convinced it actually plays out that way under actual use, but yeah, I don't really know how the costs would work out.
Not like I would ever explore this, it's so counter to the idea of what I think commit messages are actually for.
In addition to the points in this article, at work I have found that given the terrible GitHub availability story these days, it's incredibly valuable to have meaningful commit messages which can be referred to locally instead of storing all of that valuable information and context primarily in GitHub Pull Request descriptions and just phoning in the commit message body (a trend that is unfortunately way too common)
100%! I had this in the past when moving between issue trackers - you can reference i.e. a JIRA ticket or GitHub Issue, but if the server is down or completely decommissioned, you lose all that context
And yes, with the recent GitHub outages, it's very nice to be able to piece together bits of context from what's locally available
if there were any trade-offs, such as why we're executing an external command, instead of implementing a Typescript-based parser
For me, this should be a code comment next to shelling out. You want that context when reading the source code.
The commit message can say "See why in the code comment in the patch", if you need to say anything.
I've just started a new job and wanted to improve my commit messages. Because this is a fresh development I have many tasks like implement a search button, implement i18n translations etc. For me it's really hard to write a commit message explaining why I did this. When I would fix a bug the why (what happend and why does this fix it?) is easier for me to find.
Do you maybe have an example feature commit from which I can take inspiration from?
No example commits, some unsolicited advice instead, hope you don't mind.
The why comes with practice. But also, the why should ideally come before you write a single line of code.
Like, for example, why did you add that search button? Because the user needed to find their car keys? Probably no. It's because the user has many many invoices in your database, and scrolling to find a particular one is tedious.
So a naive why-message would be something like, "add a search button so that the users can find invoices by a particular vendor".
No, wait, that's not right? You also implemented a search by date? Do users ever search by date, is that a use case? Well, no, okay, let's remove the extra date search code, and the date picker library, and that will not just make for less code, the site will be faster to load.
Then you can go deeper. Like, why are they searching by vendor? Are they validating shipments against what the company paid for? Are they settling missed payments? Maybe they'd line a whole new tab or autofilter that shows then exactly those items. Then you don't even do a search button, but give them their documents right away.
Which is (part of) what the author is talking about in the linked post. If you just write what you did ("added a search by vendor and date"), it would look cool. If someone had to review your PR, they wouldn't question it. But by saying why, it makes the review (first a self-review, then hopefully a review by a teammate) easier and more critical and relevant.
Part of the practice is thinking more from a product design perspective. I don't mean it's design here, but actual product. What does it do? For whom? What problem does it solve? How can it solve the problem better?
That gets you a lot of exercise in asking the why question.
Like, for a small experiment, take your product, open any page. Or another product - this lobsters page with the commit message discussion.
Look at every single word, icon or line (aside from the user content). Why is it there? What is it's purpose? Why is it in such a colour or font? Aesthetics? Moderation? Accessibility?
Imagine having to build the page from scratch, and make each commit add just a singlr such element. There's a bunch of why committs.
"Added an up arrow so that a user can record their agreement with the conmment by giving them internet karma points. Make it small because then users have to really strongly like the comment, otherwise they wouldn't bother reaching for the mouse. "
Since playing around with jujutsu I am now trying to write my commit messages before I start the work. I often change them later, adding details etc. but it refines my purpose for the change and it is where I write the pseudo-code in point form.
"AI is just a tool". You hear this a lot.
One way that seems to break down is in its use(s). Every article I read about LLM presence in software development has the engineer handing off some part of their job to probabilistic generation, but then "retaining control" over another part. For some, it's the planning/architecture/design phase. For some it's the boilerplate code generation. For some it's the [unit] tests. For some it's the commits/git operations. It's all over the map. I know of no other "tool" that is applied with so much versatility and simultaneously passed up in so many varied areas. Tools usually have broad concensus in application. Disruptive and awesome these things are, reducing them to "tools" by way of analogy feels off. To me. YMMV.