metric_fu installation

Installing metric_fu

metric_fu is a Ruby gem, which means you can download and install it with:

sudo gem install metric_fu

The metric_fu gem specification automatically requires a number of other gems that it uses, including rcov and Flog. So installing the metric_fu gem should mean your system is ready, without the need for additional downloads and installations.

Assuming you are using metric_fu with Rails, you probably will want to tell Rails that it should look for and include the metric_fu gem. You can do this in modern versions of Rails by adding the following line to config/environment.rb:

config.gem 'jscruggs-metric_fu', :version => '0.9.0',
  :lib => 'metric_fu', :source => 'http://gems.github.com'

In other words, you want Rails to load the gem known as metric_fu, which can be downloaded from Github as jscruggs-metric_fu, version 0.9.0. If this gem does not exist, Rails will exit with an error.

Finally, you must add a line to your Rails application's Rakefile, telling it you want to load the Rake tasks associated with metric_fu:

require 'metric_fu'

Once this is complete, you should find a number of new tasks, all of whose names start with metric, available in Rake. You can list them with:

rake -T | grep metrics

I typically run all the tests, which you can invoke with:

rake metrics:all

This runs all of the software metric_fu works with, a list that has grown somewhat in the last year. At the time of this writing, running metrics:all includes:

• churn: which files change the most?

• coverage: which parts of your code are tested?

• flay: which parts of your code are duplicated?

• flog: is your code unnecessarily complex?

• reek: does your code suffer from well-known bad practices?

• saikuro: how complex is your code?

I cover a number of these tests in greater detail below. But, before continuing, it's important to note that metrics:all will fail to run all the tests if the rcov coverage tool encounters one or more errors. This isn't a problem if you test frequently, but it can bite you if you break a test and then run metrics:all.

When you run the full report with rake metrics:all, metric_fu puts all the output files under your application's tmp/metric_fu directory. Each test has its own separate subdirectory and produces output in HTML for easy reading with a Web browser. The fact that the files are put in tmp/metric_fu makes them easy to find and view on a local system, but it requires that you move them into a Web-accessible directory (for example, public/tmp/metric_fu) if you want to view them from a remote machine. It should go without saying that you don't want this information to appear on a Web site that is publicly viewable, so be sure to password-protect or delete these reports to avoid unpleasantness.

Although metric_fu's defaults work for most initial cases, you may find yourself wanting to customize one or more of its tests. You can do this within your Rakefile by adding a MetricFu::Configuration block and invoking config.*, where * is one of the tests that metric_fu brings in. For example, you can customize which tests run for :all with:

MetricFu::Configuration.run do |config|
config.metrics          = [:coverage, :flog]
end