6 ms·

I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they

I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. It’s a bit sad, but I have a growing suspicion that beautiful commit messages are a bit of vanity by the programmer. The person primarily impressed is often the author; others will walk on by without noticing. There is room sometimes for those aesthetic flourishes but I am not convinced they have much practical value, and I have stopped really being bothered by commit messages of “fix whitespace issue” from others. I think I am a better colleague for that. Things might be different on a project like Git or Linux with huge distributed teams and tons of commits, versus the projects I am used to which have between 1 and 100 contributors, mostly from the same organization.

j2kun 3y ago
I find them valuable, especially when trying to study a new codebase. In the current era where we get immediate feedback on everything we post online, it's harder to see the value that comes from writing good commits, and the value can be delayed by weeks, months, or even years.
cybrox 3y ago
If anything, this just tells us that tooling should incorporate commit messages a lot more. While these kind of messages are most valuable in large projects, there are some of them in a lot of projects and they could have saved a lot of time. Especially now with AI IDE integrations, incorporating a software's whole history into supplemental tools would be more useful than ever before.
bombcar 3y ago
> I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. They have value even if the only person who will ever look at them is you - and I will say that when bisecting an issue, the commit message of the commit I finally find is really useful (or it could be if it wasn't fixed thing). It also means that if you encounter a similar issue again, you know that there's a note on a commit you can find.
- tux3 3y ago
  In some orgs, people never run a bisect. Not once a year. They go as far as squashing out swaths of history into big un-reviewable blobs. Once code has been merged, they never look inside a past commit again. In spite of isolated (desperate) demands for rigor, it works fine.
  - tuetuopay 3y ago
    I despise squashs. It encourages people to tread git commit as a glorified ^S of their work. You want to know why a change was made, or who so that they can explain it. You land on a blob of a diff, with no meaningful commit message (any commit message was squashed to /dev/null to be replaced with the MR title and description). And then off you go to the corresponding github/gitlab/whatever MR only to find a wall of "hmmmm" "why no work?" "try something" etc commits.
    - bspammer 3y ago
      This is a false dichotomy. Someone creating the "fix problem" commits is not going to suddenly write great commit messages because the merge strategy changed. The root evil is actually MRs that live longer than a day or two, and change too much code at once.
      - mrinterweb 3y ago
        Sometimes units of work that a branch would reflect are larger. I agree there are some branches that grow larger than they should, but often there are branches that involve a good number of changes, and breaking it into smaller branches doesn't really make sense either. There will always be branches where there should be multiple meaningful commits, and automatically squashing them all together just defeats the purpose of good commit messages. I don't buy into the idea that branches should always have just one commit or be reflected as a single commit on merge.
    - adamsilkey 3y ago
      Squashes and rebaseses, used properly, are done prior to committing work into a shared major branch (like trunk or develop or whatever). The goal of the squash is to make the resulting commit atomic.
pletnes 3y ago
I often use the git blame feature in the IDE to understand what’s been going on. A good commit message will be appreciated, should I happen to find one.
Lex-2008 3y ago
I was bitten by too-short commit messages few times already, when someone asks me "why is it done this way?" - I check git history to find my own 3-year-old commit with message "it should be done this way"... Since then I try to write my commit messages so at least future me would get a hint why a change was necessary.
ajuc 3y ago
If you change a line of code without doing git-blame on it first you're doing it wrong. I've been bitten by this many times - I change obvious bug, I'm about to commit the changes, I see the previous commit which introduced the "bug" on purpose and the attached JIRA task has perfectly good explanation for why my obvious change would have reintroduced some bug from 2 years ago :)
- boolemancer 3y ago
  Seems to me that if you're introducing something that seems like a bug on purpose, you should probably have the comment in the code explaining why it's there.
- kaashif 3y ago
  > If you change a line of code without doing git-blame on it first you're doing it wrong. Working on a project where this is necessary sounds like a hellish experience. The place for comments explaining why the code is needed is right next to the code! On an adjacent line!
  - ajuc 3y ago
    > a hellish experience. It's literally 1 click away. Or even just a hover over the margin. > The place for comments explaining why the code is needed is right next to the code! On an adjacent line! And then you refactor the code (from another place) and the function name and parameters change but the comments in adjacent lines remain the same. Ups, the comments lie. After enough time passes it's 50-50 whether a particular comment is still true. The more high-level the comment - the higher likelihood it lies, because high-level comments are by their nature further away from the code they mention (and they always mention code in many places but you won't copy-paste them everywhere relevant, right? DRY and all). So in reality the comments aren't "on the adjacent line" but "on the adjacent line in one of 10 places this code is related to - go look for all of them". On the other hand commit message is always on all lines that changed, if you git blame a line - you see when it was changed last and why, and you can be sure nobody messed with it without changing the commit message.
gotts 3y ago
I agree with you that searching across commit messages happens rather rarely so return on great commit messages might be questionable where great commit messages like the one in the blog post make perfect sense are pull requests. If the commit message explains the whole thought process that the author had while working on it, it saves so much time on pull request review.
20after4 3y ago
I might be weird but I try to at least skim all of the commits on any project I am actively involved with. If it's an open source project then those commit messages will live on forever. They will even be indexed in regular search engines, not just code search (this maybe not so much now that GitHub is locking out bots more and more) When I'm trying to solve a problem and not finding results on google or stack overflow, sometimes I search GitHub just to see if a similar thing shows up in PRs or commit messages anywhere (including private repos I have access to search). It's helped me out on countless occasions. Good commit messages do have value beyond vanity, absolutely without a doubt. The fact that many developers aren't looking, that's their loss and hopefully they will see the light once they have enough experience. Maybe teach a junior dev how to search them! Maybe link them to TFA.
slily 3y ago
I agree this one goes into more detail than is useful for future reference, most of the explanation would be better off in a PR description. But in general I would rather people go into too much detail than the more common variant of not providing any contextual information anywhere (or only in a chatroom at best) and sticking to one-line commits. As long as the important information is near the top so I don't have to wade through the verbose "this is how I discovered this issue" thing, go crazy.
cheald 3y ago
IMO, the primary target audience for good commit messages is the same target audience as good code comments: me six months from now. Being able to read why and how a particular thing was done has helped me in debugging and troubleshooting an issue on more than one occasion.
kelnos 3y ago
I both agree and disagree. I think you're right that most commit messages won't end up being seen. But when you do need to see one, having a good commit message can be critical to understanding a change, especially if the person who made the change is long gone by the time you need to look at it. Or, hell, if that person was you, but it was far enough in the past that you don't recall the details.
thefourthchime 3y ago
I agree. My view is that you shouldn't write comments because if you have to, then your code isn't clear or organized well enough. If you do need a comment, perhaps to document a "Chesterton's Fence", you should put a big nice comment block to explain why and what's going on. The reality is people don't like to read, if they do it'll be an overview of how the code is organized, they don't want to read git commits or even comments. The code is the only truth. GPT can already explain in English what the code is doing pretty well already, imagine in 2-3 years.
- agubelu 3y ago
  I think the "code should be self-documenting" view is a bit simplistic. Good comments shouldn't explain what the code is doing, I agree that should be evident from the code itself if it's clear enough. However, why the code is doing what it's doing, or why it's being done in a certain way and not in a different way, is meta-information that is very hard to express in the code itself, and that's where comments are most useful.
cerved 3y ago
Worse, PR tools like Azure DevOps (and GitHub?) don't do a good job of displaying the information. Just a big diff. I often get asked about the reason for a change in a review comment, even when there's a thorough description in the backing commit. It's sad. I would prefer PRs over email like Git does

j2kun 3y ago

I find them valuable, especially when trying to study a new codebase. In the current era where we get immediate feedback on everything we post online, it's harder to see the value that comes from writing good commits, and the value can be delayed by weeks, months, or even years.

cybrox 3y ago

If anything, this just tells us that tooling should incorporate commit messages a lot more. While these kind of messages are most valuable in large projects, there are some of them in a lot of projects and they could have saved a lot of time. Especially now with AI IDE integrations, incorporating a software's whole history into supplemental tools would be more useful than ever before.

bombcar 3y ago

> I have felt that pride in writing a great commit message, but I am less sure of the value to others. I don’t think most people search commit messages when they encounter an unusual error message, or when adding a new feature, or really almost ever. They have value even if the only person who will ever look at them is you - and I will say that when bisecting an issue, the commit message of the commit I finally find is really useful (or it could be if it wasn't fixed thing). It also means that if you encounter a similar issue again, you know that there's a note on a commit you can find.

tux3 3y ago
In some orgs, people never run a bisect. Not once a year. They go as far as squashing out swaths of history into big un-reviewable blobs. Once code has been merged, they never look inside a past commit again. In spite of isolated (desperate) demands for rigor, it works fine.
- tuetuopay 3y ago
  I despise squashs. It encourages people to tread git commit as a glorified ^S of their work. You want to know why a change was made, or who so that they can explain it. You land on a blob of a diff, with no meaningful commit message (any commit message was squashed to /dev/null to be replaced with the MR title and description). And then off you go to the corresponding github/gitlab/whatever MR only to find a wall of "hmmmm" "why no work?" "try something" etc commits.
  - bspammer 3y ago
    This is a false dichotomy. Someone creating the "fix problem" commits is not going to suddenly write great commit messages because the merge strategy changed. The root evil is actually MRs that live longer than a day or two, and change too much code at once.
    - mrinterweb 3y ago
      Sometimes units of work that a branch would reflect are larger. I agree there are some branches that grow larger than they should, but often there are branches that involve a good number of changes, and breaking it into smaller branches doesn't really make sense either. There will always be branches where there should be multiple meaningful commits, and automatically squashing them all together just defeats the purpose of good commit messages. I don't buy into the idea that branches should always have just one commit or be reflected as a single commit on merge.
  - adamsilkey 3y ago
    Squashes and rebaseses, used properly, are done prior to committing work into a shared major branch (like trunk or develop or whatever). The goal of the squash is to make the resulting commit atomic.

pletnes 3y ago

I often use the git blame feature in the IDE to understand what’s been going on. A good commit message will be appreciated, should I happen to find one.

Lex-2008 3y ago

I was bitten by too-short commit messages few times already, when someone asks me "why is it done this way?" - I check git history to find my own 3-year-old commit with message "it should be done this way"... Since then I try to write my commit messages so at least future me would get a hint why a change was necessary.

ajuc 3y ago

If you change a line of code without doing git-blame on it first you're doing it wrong. I've been bitten by this many times - I change obvious bug, I'm about to commit the changes, I see the previous commit which introduced the "bug" on purpose and the attached JIRA task has perfectly good explanation for why my obvious change would have reintroduced some bug from 2 years ago :)

boolemancer 3y ago
Seems to me that if you're introducing something that seems like a bug on purpose, you should probably have the comment in the code explaining why it's there.
kaashif 3y ago
> If you change a line of code without doing git-blame on it first you're doing it wrong. Working on a project where this is necessary sounds like a hellish experience. The place for comments explaining why the code is needed is right next to the code! On an adjacent line!
- ajuc 3y ago
  > a hellish experience. It's literally 1 click away. Or even just a hover over the margin. > The place for comments explaining why the code is needed is right next to the code! On an adjacent line! And then you refactor the code (from another place) and the function name and parameters change but the comments in adjacent lines remain the same. Ups, the comments lie. After enough time passes it's 50-50 whether a particular comment is still true. The more high-level the comment - the higher likelihood it lies, because high-level comments are by their nature further away from the code they mention (and they always mention code in many places but you won't copy-paste them everywhere relevant, right? DRY and all). So in reality the comments aren't "on the adjacent line" but "on the adjacent line in one of 10 places this code is related to - go look for all of them". On the other hand commit message is always on all lines that changed, if you git blame a line - you see when it was changed last and why, and you can be sure nobody messed with it without changing the commit message.

gotts 3y ago

I agree with you that searching across commit messages happens rather rarely so return on great commit messages might be questionable where great commit messages like the one in the blog post make perfect sense are pull requests. If the commit message explains the whole thought process that the author had while working on it, it saves so much time on pull request review.

20after4 3y ago

I might be weird but I try to at least skim all of the commits on any project I am actively involved with. If it's an open source project then those commit messages will live on forever. They will even be indexed in regular search engines, not just code search (this maybe not so much now that GitHub is locking out bots more and more) When I'm trying to solve a problem and not finding results on google or stack overflow, sometimes I search GitHub just to see if a similar thing shows up in PRs or commit messages anywhere (including private repos I have access to search). It's helped me out on countless occasions. Good commit messages do have value beyond vanity, absolutely without a doubt. The fact that many developers aren't looking, that's their loss and hopefully they will see the light once they have enough experience. Maybe teach a junior dev how to search them! Maybe link them to TFA.

slily 3y ago

I agree this one goes into more detail than is useful for future reference, most of the explanation would be better off in a PR description. But in general I would rather people go into too much detail than the more common variant of not providing any contextual information anywhere (or only in a chatroom at best) and sticking to one-line commits. As long as the important information is near the top so I don't have to wade through the verbose "this is how I discovered this issue" thing, go crazy.

cheald 3y ago

IMO, the primary target audience for good commit messages is the same target audience as good code comments: me six months from now. Being able to read why and how a particular thing was done has helped me in debugging and troubleshooting an issue on more than one occasion.

kelnos 3y ago

I both agree and disagree. I think you're right that most commit messages won't end up being seen. But when you do need to see one, having a good commit message can be critical to understanding a change, especially if the person who made the change is long gone by the time you need to look at it. Or, hell, if that person was you, but it was far enough in the past that you don't recall the details.

thefourthchime 3y ago

I agree. My view is that you shouldn't write comments because if you have to, then your code isn't clear or organized well enough. If you do need a comment, perhaps to document a "Chesterton's Fence", you should put a big nice comment block to explain why and what's going on. The reality is people don't like to read, if they do it'll be an overview of how the code is organized, they don't want to read git commits or even comments. The code is the only truth. GPT can already explain in English what the code is doing pretty well already, imagine in 2-3 years.

agubelu 3y ago
I think the "code should be self-documenting" view is a bit simplistic. Good comments shouldn't explain what the code is doing, I agree that should be evident from the code itself if it's clear enough. However, why the code is doing what it's doing, or why it's being done in a certain way and not in a different way, is meta-information that is very hard to express in the code itself, and that's where comments are most useful.

cerved 3y ago

Worse, PR tools like Azure DevOps (and GitHub?) don't do a good job of displaying the information. Just a big diff. I often get asked about the reason for a change in a review comment, even when there's a thorough description in the backing commit. It's sad. I would prefer PRs over email like Git does