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.

Rails Plugin Versioning

James Mead — Sat, 02 Dec 2006 09:36:00 +0000

A while ago Jay Fields described a number of ways to share Ruby code between projects and focussed on a useful technique which involves using RubyGems and unpacking them into your vendor directory. He also mentions the difficulties of versioning with Rails plugins.

We use a number of Rails plugins at Reevoo. Initially we used Subversion externals to include them in our projects, but for a while now we’ve been successfully using François Beausoleil’s Piston which is effectively an extension to Subversion. You end up with a copy of the plugin code in your own repository with the relevant revision number from the remote repository stored in your own Subversion metadata. Piston prevents you getting new versions of the plugin code every time you update (as you would with an svn:external) which can lead to unexpected changes, but makes it straightforward to update to a newer version of a plugin when you want.

You can find Piston here.

Floehopper: Tag version

Prefer Commit Notes over Comments

Rails Plugin Versioning