Prefer Commit Notes over Comments

James Mead — Sat, 29 Mar 2008 19:05:00 +0000

My colleague, Chris, recently posted about what makes a good commit note. His main point is that a good commit note should explain why the changeset exists rather than what it contains (which should be more self-evident). I agree with this and (as Chris mentions) it’s of particular benefit when you have to do some software archeology. I’d go a step further and say that, for me, the best commit notes express the business reason for the changeset. If as a developer you are struggling to explain the business case for a particular change, (imho) you should try to find out before committing – otherwise how do you know the changeset is delivering value to the business?

In a previous post about preferring tests over comments, I expressed similar sentiments about using comments and tests to explain why rather than what. Chris’ post prompted me to re-read that old post and I noticed that it didn’t explain why I prefer tests over comments. The reason is that comments have a nasty habit of becoming out-of-date and getting left lying around to confuse the unwary, whereas you are forced to keep tests up-to-date (assuming they are part of a continuous integration build). For similar reasons I also think that commit notes are better than code comments, because they are forever associated with a snapshot of the code at the time they were written – leaving less scope for confusion.

Prefer Tests Over Comments

James Mead — Thu, 10 May 2007 15:29:00 +0000

One small a-ha moment in my early programming days was when someone suggested it was better to write a comment explaining why a chunk of code worked the way it did, rather than simply describing how it worked – essentially a direct translation of the code into english sentences.

Since then I’ve become a test-infected, test-driven developer and now I would always choose to write a test in preference to writing a comment. But I think the same lesson still applies…

I’ve recently been making a conscious effort to come up with better test names. The easy option is for the test name to reflect what happens in the test. But it makes the test much more valuable if you can use the test name to explain why the behaviour is the way it is.

Comments are also often used as to-do items, but I think tests can be a better solution. For example, Ben mentions leaving notes for the team in tests.

Floehopper: Tag comment

Prefer Commit Notes over Comments

Prefer Tests Over Comments