3 ms·

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

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"

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"