A Guide to Choosing the Best Gems for Your Ruby Project

If you need something done in Ruby, a gem for it probably exists. Well, a dozen gems for it probably exist. Some of them are elegant, featureful, and well-maintained, and others were written to solve one use case the author ran into that one time. You have lots of gems to choose from, so how do you choose the right one? This choice is important – by the time you regret adding a gem to your project, it’s painful to change back.

The stats

When I need a library to solve a problem I’m having, I start with the Ruby Toolbox. The Ruby Toolbox is a great way to get a list of all the gems in a category (like “Subscription Management”), along with:

• How many people use it?

  Popular gems are usually more popular for a reason. And it’ll be much easier to get help if everyone else on the internet is using the same gem.

• How recently / often is it updated?

  Does the gem get consistent updates, or is that Rails 3.2 compatibility upgrade still sitting in the pull request queue? If the last release was years ago, you might want to skip it – it probably wouldn’t be compatible with your app, anyway.

With the gems you find on the Ruby Toolbox, filtered by those first two criteria, you should have a list of gems you’re actively considering. The Ruby Toolbox also gives you links to the source, the documentation, the website, and the bug tracker, which you’ll need next.

The code & documentation

• Is the gem well documented?

  Check the website, if it has one. Is the documentation good? Does it have RDoc? Are you going to be able to find the answers you need when you need them?

• Is it well-tested?

  Take a look at the tests. Does it even have a test/ or spec/ directory? Does it have any tests beyond test_truth? Is the author going to know if they cause a regression?

• Look at the issues and pull requests

  Do bugs get fixed quickly? Is there discussion on the bugs and pull requests, and do they get fixed? Or do they just kind of sit there?

• Search for the gem’s name on Google, StackOverflow, and reddit

  What do people say about it? Which gems get recommended, and which ones are discouraged?

• Search GitHub for a few of the classes provided by the gem

  How are they used in real-world apps? Do they seem easy to use? Or do other developers have to hack around problems in the gem?

At this point you should have your choice narrowed down to a few remaining candidates.

The touchy-feely stuff

These criteria are a little subjective, which is why you have to find the right gem for your project. But if you miss on these, you’ll regret it later.

• Based on the examples in the documentation, does the library feel Ruby-ish?

  Does it use Ruby idioms? Or do you feel like you’re actually writing Java or PHP? This happens incredibly often to API wrappers.

• Is it built out of small parts that work well together?

  Can you use the objects the author gave you to build things the author never thought of? Because you’ll probably want to.

• Is the gem already used by another gem that’s already in your project?

  Bonus, you just saved yourself some integration time, and you know you won’t have to fight with Bundler over versioning.

• Does the gem make assumptions about your app? Does your app fit those assumptions, and will it always fit them?

  Some gems, like ActiveResource, make assumptions about the API of the server they talk to. Others, like ResourceController, make assumptions about what your controller will do. Gems that make assumptions can make you much faster and your code much simpler–while those assumptions hold. If those assumptions become incompatible with your app, though, you’ll find yourself spending days monkey patching, debugging, and eventually just tearing the gem out.

Whoa, that’s a lot.

Yep, there’s a ton of criteria you can use to pick the best gem for your project. And you usually won’t have to go through them all. Most of the time, you can just hop on the Ruby Toolbox and pick the most popular gem.

But there are some gems that become core parts of your app. Things like HTTP libraries, database libraries, or anything that promises to make your controllers cleaner. And it’s worth taking the extra time making sure that these gems are clean, well-maintained, well-documented, and fit your mental model of how they should work.

I put all these criteria in a Google Spreadsheet, so when you need to pick from an overwhelming number of seemingly similar gems, you can easily compare them. You can grab it here.