Ask HN: Should commit summaries describe the change, or the intent? | Hacker News Reader

Ask HN: Should commit summaries describe the change, or the intent?

21 pointscsnover19 comments

I recently received some advice that the summary line of a Git commit message should describe what the change does. In particular, they said to avoid summaries in the form of “Fix <broken thing>”.

For example, instead of “Fix wrong default font for FooComponent on BarPlatform”, write “Explicitly inherit BazComponent font for FooComponent on BarPlatform”. Or instead of “Optimise FooFunction memory use to improve performance”, write “Reuse existing heap allocations on BarObject in FooFunction”.

On the one hand, I can see that writing summaries this other way communicates more specific detail about what changed; “Fix <broken thing>” could mean anything happened. On the other hand, what the change does is already described by the code, so focusing the summary on why the change was made instead seems much more beneficial.

This is probably more of a ‘spaces versus tabs’ kind of thing where the answer doesn’t matter too much, but I am curious to hear from others on which approach you have found most beneficial in your work. In particular, if anyone uses this style of “describe the change” summarisation, have you experienced any particular benefits that might not be obvious? Thanks!

> Should commit summaries describe the change, or the intent?

Yes.

Intent first, then a high level summary of the changes (if non-trivial).

Some programmers say that the code is the documentation and that comments in code are a "code smell". I strongly disagree.

The code is a communication between the programmer and the compiler, and leaves out intent. The code does what it does, right or wrong. But what we care about is what we intended the code to do, and why.

So intent is more important because the code could be wrong.

I guess it depends on the context in which you are seeing the message.

For me, the most likely context is through blame or similar - I am looking at some code, and trying to understand its history. I see who changed it, when - and their commit message. In which case, only the intent is useful - I already likely know what the change does.

The "what it does" form is more useful if for some reason you're scanning commits trying to find the one that introduced some particular change. But that's not a use case I ever encounter.

> The "what it does" form is more useful if for some reason you're scanning commits trying to find the one that introduced some particular change. But that's not a use case I ever encounter.

I've encountered it many times.

I didn't mean to imply that others wouldn't.

What you are describing basically matches my experience. Whether I’m doing a blame or a code review, if I’m reading commit messages, I’m doing it to understand why some thing is the way it is. Reciting what changed in 70 characters instead of saying why it changed doesn’t feel like it helps me much.

For the case of trying to find a change, I’d personally just run `git log -G` or `git log <file glob>` depending on what I’m looking for. I suppose one must know that these commands exist, though, so maybe that’s part of it.

> The "what it does" form is more useful if for some reason you're scanning commits trying to find the one that introduced some particular change. But that's not a use case I ever encounter.

There are at least two use cases where I find it useful: 1. To review (recent) changes when you have no time to read full diffs but may hope that git commit messages will give a good idea what was changed since the previous review. There are many repos I follow and reading logs takes less time than diffs. 2. To find out when some change was made for which I know keywords to look in a message but not the code (and then I can check a diff to see the code).

Why is indeed very important but a good commit messages can have booth: a short summary for what was changed and why.

Yeah those use cases make sense!

All of it. It's a brain dump of where you are when you did the thing. Three years from now, you're going to want it to figure out what you're thinking when you wrote that bit of code. Future you is going to appreciate it. And then add in doing that for other people that come across your code as well.

This will improve your commit messages:

https://cbea.ms/git-commit/

Rebase.

Intent. You can always get diffs of one commit vs another. You can't always discern why those changes happened

The changes should be the main meat of most commit messages and if the intent or other options considered add value to that then they should be included below.

The reality is if the intent, other options, relevant notes etc are not valuable then they will be lost to time (no loss). If they are valuable where else are you going to put them? Some wiki or knowledge store for your project? How will you know that this specific commit and that (probably) sparse text in said knowledge store are related? Why not just put them together where they belong anyway.

Commit messages are not valuable when they are maximally short. They are valuable when they describe the changes the commit applies and ANY other relevant information for people (including the author(s)) in the future so that said people can understand the commits effect and other relevant information.

For an example of amazing commit messages look at PostgreSQL’s. They are sometimes long with the changes, notes, intent etc and sometimes short.

The commits should describe your current mood diary-style.

git commit -m "procaffeinating."

git commit -m "fixed the bug that made me question my life"

git commit -m "Felt cute, might delete later"

git commit -m "embracing insomnia ..."

Individual git commits often get squashed so I typically don't put much thought into them.

Pull requests, on the other hand, have an explanation/justification for the change and a summary of changes.

My workflow is to create a pull request containing all the commits, squashed. So the title of the PR is really what matters, but then again, the PR itself contains great metadata, like the description, and the link to Linear, or whatever task planning tool.

To get PR metadata one have to go to github/gitlab but for many people (including me) it is more convenient to have all history in git locally. So I thankful when people put the same information both into commit messages and into PR descriptions and do the same myself. It can be automated to some degree.

I don't think there is a should in this that doesn't, if you dig a bit, eventually boil down to personal preference. Hume's law and all that.

Check out https://www.conventionalcommits.org

Just pipe in https://whatthecommit.com

Reply on news.ycombinator.com