3 ms·

My take: these aren’t good commit messages. The verb isn’t supposed to be what you did, otherwise it would always be “add” or “change” or “fix”. The verb is sup

My take: these aren’t good commit messages. The verb isn’t supposed to be what you did, otherwise it would always be “add” or “change” or “fix”. The verb is supposed to be what the program does thanks to this change. E.g. “Check server fingerprint”, not “Add server fingerprint check”. We already know you changed or added something, it’s a git commit.

MatekCopatek 8y ago
But how would you name the commits that fix, refactor and remove that same feature? "Check server fingerprint with less errors", "Check server fingerprint in a different way" and "Check server fingerprint no more"?
- matthewmacleod 8y ago
  “Handle timeout errors when checking server fingerprint”, “Use new API endpoint for server fingerprint”, and “Replace server fingerprint checking with magic”. You can still use those verbs, but the interesting thing in commit messages is what they do, rather than what changes you made. A commit message is really like a small note to future contributors; it’s not always easy to write them, but it’s always worth thinking about them from the perspective of someone who is looking at them two or three years hence.
  - usrusr 8y ago
    But "Replace server fingerprint checking with magic" has clearly crossed the line from "the verb describes what the code does" to "the verb describes what the developer did". "Note to future contributors" is spot on of course. The best way to write better commit messages is to consume the existing corpus as often as possible, e.g. by never trying to understand code without the blame column active in your editor of choice. My preferred format is a condensed why-what, consisting of "$verb $ticket $wherein": $verb would be the developer activity, like fix/optimize/remove/.., and it is mostly there to make it clear that the rest of the message should not describe developer activity. $ticket would reference your beloved issue tracking system (an additional short keyword describing the issue doesn't hurt as a checksum and to prevent excessive referencing, but it has to be optional because a bad keyword is worse than none). $wherein would be the customary quick rundown of how the code is supposed to work, expect future readers to only read the beginning. I like this order because it gives a rudimentary sentence structure to the formulaic parts and positions them at the beginning where they can never be pushed below the fold by the potentially rambly description of the code. Anything more complicated than that will degrade harder when rules are not followed to the letter. Perfect is the enemy of good.
- freehunter 8y ago
  In my case I have commits that say "check server fingerprint" then "check server fingerprint but this time it works in production" and then "check server fingerprint but this time it ACTUALLY works in production" followed by "check server fingerprint works in dev and test what is actually happening here" and the final commit of "i hate everything about all of this". Of course that last unhelpful commit message is tied to the code that actually works in production so it's what sticks.
  - usrusr 8y ago
    The good news is that you apparently fixed it already at "I hate everything", which is still a number of commits before trying to recite the Macarena from memory. A good rule/guideline for commit messages should not only help us writing perfect messages when we would otherwise write merely good ones, but also scale down to encourage mediocre messages when we completely stopped caring. "rerere ISSUE-123 there is no hope"
harg 8y ago
But that's not how git itself makes commit messages: (`Merge branch 'foo'`, `Revert 'some thing'`) Not every commit changes how the code works. Some is just documentation-related, or formatting, or some other configuration change. The list goes on. Your approach would only make sense in a subset of cases. IMO the message should be what the commit does, not what the code does.
- craftyguy 8y ago
  Git doesn't know enough about the code to make more meaningful messages, so maybe git messages should not be the standard that developer messages strive to meet.
deleted 8y ago
[deleted]

MatekCopatek 8y ago

But how would you name the commits that fix, refactor and remove that same feature? "Check server fingerprint with less errors", "Check server fingerprint in a different way" and "Check server fingerprint no more"?

matthewmacleod 8y ago
“Handle timeout errors when checking server fingerprint”, “Use new API endpoint for server fingerprint”, and “Replace server fingerprint checking with magic”. You can still use those verbs, but the interesting thing in commit messages is what they do, rather than what changes you made. A commit message is really like a small note to future contributors; it’s not always easy to write them, but it’s always worth thinking about them from the perspective of someone who is looking at them two or three years hence.
- usrusr 8y ago
  But "Replace server fingerprint checking with magic" has clearly crossed the line from "the verb describes what the code does" to "the verb describes what the developer did". "Note to future contributors" is spot on of course. The best way to write better commit messages is to consume the existing corpus as often as possible, e.g. by never trying to understand code without the blame column active in your editor of choice. My preferred format is a condensed why-what, consisting of "$verb $ticket $wherein": $verb would be the developer activity, like fix/optimize/remove/.., and it is mostly there to make it clear that the rest of the message should not describe developer activity. $ticket would reference your beloved issue tracking system (an additional short keyword describing the issue doesn't hurt as a checksum and to prevent excessive referencing, but it has to be optional because a bad keyword is worse than none). $wherein would be the customary quick rundown of how the code is supposed to work, expect future readers to only read the beginning. I like this order because it gives a rudimentary sentence structure to the formulaic parts and positions them at the beginning where they can never be pushed below the fold by the potentially rambly description of the code. Anything more complicated than that will degrade harder when rules are not followed to the letter. Perfect is the enemy of good.
freehunter 8y ago
In my case I have commits that say "check server fingerprint" then "check server fingerprint but this time it works in production" and then "check server fingerprint but this time it ACTUALLY works in production" followed by "check server fingerprint works in dev and test what is actually happening here" and the final commit of "i hate everything about all of this". Of course that last unhelpful commit message is tied to the code that actually works in production so it's what sticks.
- usrusr 8y ago
  The good news is that you apparently fixed it already at "I hate everything", which is still a number of commits before trying to recite the Macarena from memory. A good rule/guideline for commit messages should not only help us writing perfect messages when we would otherwise write merely good ones, but also scale down to encourage mediocre messages when we completely stopped caring. "rerere ISSUE-123 there is no hope"

harg 8y ago

But that's not how git itself makes commit messages: (`Merge branch 'foo'`, `Revert 'some thing'`) Not every commit changes how the code works. Some is just documentation-related, or formatting, or some other configuration change. The list goes on. Your approach would only make sense in a subset of cases. IMO the message should be what the commit does, not what the code does.

craftyguy 8y ago
Git doesn't know enough about the code to make more meaningful messages, so maybe git messages should not be the standard that developer messages strive to meet.

deleted 8y ago

[deleted]