Comments in Gemfile

I wish people would take a little time to consider the best way to arrange and comment the gem insertions in Gemfile.

I am not a great fan of commenting. I believe you should code so that it is easily readable without comments. When I see comments, I tend to think “There’s a bit of code that the developer doesn’t think people will be able to understand”. Commented methods are usually the ones in prime need of refactoring.

However, there are times where you have little option but to use unintuitive code patterns and a short comment is then required.

One of the best examples of this, and one where I rarely see any comments is the Gemfile. All the team developed rails apps I have worked on, have a range of different gems. I sometimes wonder whether most rails developers measure their skill level on the number of gems they can add to the Gemfile. It’s certainly become an interview criteria!

Many gems have functionality that is not obvious from their name. For example, nokogiri (Japanese symbol for ‘saw’ I believe), is not a name that makes it obvious to me that it is an html parser. I do not think that is the fault of the gem developer. You have to come up with a unique name, and that is not easy. Especially if you want to make it memorable.

It is usually fairly easy to find the gem’s project in github and/or via a google search, and then to find out what it does. It is very rare for a commonly used gem not to have at least a basic description of its functionality in its README (polyamorous being one exception).

The problem is do you really want to have to look up every gem README when you are scanning through a Gemfile looking for where some functionality you don’t recognise, may be added. Some short comments can make this task so much easier.

I’m working on an application that uses Postgres, and the models are being queried with search_by_title_and_body, and I couldn’t see where the search_by functionality was coming in. It took me a few minutes looking through the Gemfile and look up READMEs, to find that ‘texticle’ was the source. This was far down in the Gemfile and amongst unrelated gems.

So I moved it to the ‘pg’ gem declaration and added a comment. I did the same for ‘activerecord-postgis-adapter’:

Now I hope the next developer who reads the Gemfile, will find it a little easier to identify the functionality being added by these gems.

Update

There is now a gem call grub, that will automatically add comments to you Gemfile. I’d highly recommend you have a look at it.