Commit comments... more is more

First off I must say that it has been a long time since I last posted - I have just been swamped with work on www.sanlamconnect.co.za.

The other day the issue of what is a good commit comment came up... and there are a number of approaches to this issue.

The big question is, Should it stand alone? IOW should it make sense by itself, or should it be taken in conjunction with diff. If you apply the former then the comment will repeat what the developer can ascertain from the diff and typically add more information. If you apply the latter then the developer is required to look at the diff to make sense of what is going on.

So the other day a fellow developer accused me of being too terse in my commit comment, and I was a little indignant at his criticism because I regarded my commit comments as being adequate. I felt why must I rehash what the user can see from the diff. The comment as far as I remember was "fixing bug"...

I reasoned, if the user has any sense they can look at the diff and they can figure out what the bug was and what I did to fix it.

But would it have killed me to just put down maybe another 10 words to indicate more details, like "fixed bug in execute target, the file extension was placed incorrectly". Is that too much to ask? Another 10 words that would have taken me another second to write that is going to save the next person at least the time it takes to open the diff, notwithstanding the time it's going to take them to make sense of it.

So, the conclusion is, write detailed commit comments. Definitely a paragraph is not necessary, but at least 10 words is a good start.

What about those developers that would have taken another minute to write those 10 words because they can't touch type... to them I say, tough, it's time you learnt.