Writing good commit messages | Hacker News Reader

Writing good commit messages

chiark.greenend.org.uk

38 pointsfanf221 comments

Good stuff here. I joined a team years ago that had a pretty solid and consistent practice of writing thorough commit messages, while still being somewhat concise. We made good use of the space to also include links to reference docs/tickets/etc. for follow up. This was incredibly useful in the long run when we’d be bisecting changes to identify a bad commit or just understanding the history of a small but important change (eg: why did we set this flag?). Its effectively free documentation space that costs nothing to add detail to.

It costs having to bisect to find it instead of just reading the code/doc

I am 100% against overdoing commit messages for the reason that if it’s important enough to document then it should be in the code or docs, not a commit message. They’re just not a functionally discoverable form of documentation.

Commit messages can be good for providing context as to why something is changing, but all context as to how it works should be formalized elsewhere. For example, a commit message that tells you how something works could immediately become misleading when functionality is changed in the future. And you’d have to consume the whole chain of commits to begin to understand that.

Personally, I overdocument everything with verbose comments in code that explain things in detail, as well as the context, thought processes, and assumptions behind it. I have found that it creates a codebase you can read more like a book, which makes it so much easier to build context. I haven’t measured it exactly, but if I had a 1000 LoC file, I’d say 600+ lines would be comments.

My comment was not meant to intend commit messages be the sole form of documentation. I am also a big fan of good code comments, docs, etc. Just prefer a lengthy commit message (when warranted) over short meaningless messages (eg: “changed thing”). Most useful in my experience is quickly grepping git log for keywords if im searching for a relevant change.

This seems like some sort of polarizing issue for some, but the reasons "why not" are totally unclear to me. I'm a regular advocate for detailed and self-explanatory code change "commit" descriptions, and I feel as if I'm in the minority trying to advocate for (at a minimum) proper bug tagging and context links in description for PRs that I come across.

This gets omitted sufficiently often that I have largely given up on requiring it except for noteworthy code changes that I am a reviewer for. It's a very hard thing to get consistent adherence to in my experience. I highly recommend others in a similar boat to at least lead by example and annotate your code changes consistently so you can at least identify relevant changes that you wrote. Getting everybody else to is another story...

For me, it's a time, and more important attention, tradeoff. I have never once needed to bisect commits to figure out why/who made a change. A blame can lead to a PR, which is usually auto linked to a ticket or has some relevant convos. Commit messages feel like a relic of the past (to me, and my teams workflow). Ymmv!

PR/ticket are additional levels of indirection. It’s more convenient when you can run git show for revision from blame and get all necessary information. Also people (teams) who write bad commit messages often write bad ticket descriptions/comments too.

The main thing I consider now is writing the commit message so that if I'm scanning it I'll know what I changed.

I only use squash and merge now, no more reverting reverts, no more merge commits. So the PR or MR title is the commit message, which means writing good PR / MR titles.

> Most of the standard tools which come with the version control system itself will display the message as plain text, without even re-wrapping the lines.

> Therefore, write your message so that it’s still readable in that form.

Therefore you should use better tools and push for improvements in the standard instead of wasting time worrying about such text luxuries as line wrapping

The thing is, one-way improvement is possible by using better tools, but if you force wrapping with newlines than good tools won't be able to fix it

For solo-private projects, I constantly catch myself writing full commit messages even though I never read it again, and `git commit -m "."` would suffice.

git commit -mm works and is a bit quicker

Not needed unless youre writing a kernel.

How many times a year do you really run a bisect? I run it like twice or thrice tops.

No one reads git history any way. Instead of writing commit messages, better write code.

If you write good commit messages, you’ll read them when you come across them. Debugging a problematic commit is less painful when its commit message teleports you back in time to when it was written, and clearly expresses the intent of the change.

I absolutely do rely on commit messages, and ask for good ones during code review. Everybody on call needs to know how to find root causes in "git log" at 3 AM. The source can't serve the same purpose; including the complete history of what changed when and by whom would make it unreadable (especially things that used to be there but aren't now).

I do, but all I really need from the git is who, when, and a reference to a ticket. The code itself- combined with who wrote and when will generally tell me all I need to know. From there, a ticket will give me the any extra context might need.

That's just storing the information in a commit message in a separate database. Fine so long as you maintain the cross-links.

But ticket systems are less stable than commit messages. Some companies decide to migrate to a new ticket system without migrating all the old "unnecessary" stuff.

Somehow, in less than 2 decades, people forgot that there was life before git. Before commit messages became compulsory, we used to write comments right in the code. And that was fine.

They serve different purposes, and yeah, you can go without (either commit messages or comments, or even source code), but it just makes certain investigations more difficult, sometimes many times so.

Counter-anecdata: I read git history extremely frequently, across a variety of projects. Useless commit messages suck.

Reply on news.ycombinator.com