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.

CruiseControl.rb for Mocha

James Mead — Thu, 05 Apr 2007 12:59:00 +0000

We have our own home-grown continuous integration application at work, but a couple of weeks ago, I decided to have a go at getting CruiseControl.rb up and running at home for Mocha. It all went pretty smoothly and I’m happy with the result. Thanks are due to the CruiseControl.rb team for clear instructions and a simple-to-use application.

I’d like to publish the url for my CruiseControl instance, but I’m concerned about random punters clicking the build button and loading my already creaking server, so a screenshot will have to suffice for now…

It would be nice if you only saw the build button if you were logged in. I feel a feature request coming on…

On a related note, it’s great to see that there has been some effort going into getting a RubyOnRails CruiseControl.rb instance set up.

Floehopper: Tag control

Prefer Commit Notes over Comments

CruiseControl.rb for Mocha