4 ms·

Writing good commit messages

38 points by fanf2 2y ago

captainkrtek 2y ago
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.
- eviks 2y ago
  It costs having to bisect to find it instead of just reading the code/doc
  - appplication 2y ago
    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.
    - captainkrtek 2y ago
      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.
cynicalsecurity 2y ago
No one reads git history any way. Instead of writing commit messages, better write code.
- chatmasta 2y ago
  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.
- erik_seaberg 2y ago
  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).
- move-on-by 2y ago
  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.
  - rcxdude 2y ago
    That's just storing the information in a commit message in a separate database. Fine so long as you maintain the cross-links.
  - funcDropShadow 2y ago
    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.
- okaleniuk 2y ago
  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.
louwhopley 2y ago
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.
- aidenscott2016 2y ago
  git commit -mm works and is a bit quicker
ElijahLynn 2y ago
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.
Willish42 2y ago
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...
- _dark_matter_ 2y ago
  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!
  - citrin_ru 2y ago
    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.
eviks 2y ago
> 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
danlugo92 2y ago
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.

38 points by fanf2 2y ago

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.

eviks 2y ago
It costs having to bisect to find it instead of just reading the code/doc
- appplication 2y ago
  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.
  - captainkrtek 2y ago
    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.

cynicalsecurity 2y ago

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

chatmasta 2y ago
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.
erik_seaberg 2y ago
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).
move-on-by 2y ago
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.
- rcxdude 2y ago
  That's just storing the information in a commit message in a separate database. Fine so long as you maintain the cross-links.
- funcDropShadow 2y ago
  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.
okaleniuk 2y ago
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.

louwhopley 2y ago

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.

aidenscott2016 2y ago
git commit -mm works and is a bit quicker

ElijahLynn 2y ago

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.

Willish42 2y ago

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...

_dark_matter_ 2y ago
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!
- citrin_ru 2y ago
  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.

eviks 2y ago

> 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

danlugo92 2y ago

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.