3 ms·

“Handle timeout errors when checking server fingerprint”, “Use new API endpoint for server fingerprint”, and “Replace server fingerprint checking with magic”.

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

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.