Hi! I hope this is useful. I wrote it because I got frustrated trying to find out why someone did something 6 months ago, and the commit message wasn’t helpful at all. I wanted to have something to point to, so I wrote this to post it.
Just like comments, good commit messages don’t tell you what, they tell you why. Small commits help make the what obvious, but the why still needs to be explained.
float Q_rsqrt( float number )
{
long i;
float x2, y;
const float threehalfs = 1.5F;
x2 = number * 0.5F;
y = number;
i = * ( long * ) &y; // evil floating point bit level hacking
i = 0x5f3759df - ( i >> 1 ); // what the fuck?
y = * ( float * ) &i;
y = y * ( threehalfs - ( x2 * y * y ) ); // 1st iteration
// y = y * ( threehalfs - ( x2 * y * y ) ); // 2nd iteration, this can be removed
return y;
}
…and the above example still has better commenting than most commit messages I’ve seen outside of work.
You obviously know, but that constant has a long history. :) This blog post discusses why it works… It took a highly visible discussion about the authorship to figure out who actually invented it. At one point it had been attributed to John Carmack, but he wasn’t the original source.
I agree the why is important. I prefer it goes into a ticket system rather than commit messages, especially if a chance spans multiple repos. But one has to be a particular size for that to be worth while.
I generally try to make PRs so small they don’t need a commit message. Some good advice for new developers here.
Just like comments, good commit messages don’t tell you what, they tell you why. Small commits help make the what obvious, but the why still needs to be explained.
To wit:
…and the above example still has better commenting than most commit messages I’ve seen outside of work.
You obviously know, but that constant has a long history. :) This blog post discusses why it works… It took a highly visible discussion about the authorship to figure out who actually invented it. At one point it had been attributed to John Carmack, but he wasn’t the original source.
Amusing example.
I agree the why is important. I prefer it goes into a ticket system rather than commit messages, especially if a chance spans multiple repos. But one has to be a particular size for that to be worth while.
Mandatory xkcd reference