Excellent¶ ↑

Excellent *finds the nasty lines in your code*. It implements a comprehensive set of checks for possibly buggy parts of your app that would *otherwise make it into your repo and eventually to the production server*.

See the API documentation at docs.github.com/simplabs/excellent and the WIKI at wiki.github.com/simplabs/excellent. Join the Google Group and discuss about the future and possibilities of Excellent: groups.google.com/group/excellent-gem.

Excellent also has a CI server set up at ci.simplabs.com/excellent.

Installation¶ ↑

Simply install with Ruby Gems:

gem sources -a http://gems.github.com
sudo gem install simplabs-excellent

Example¶ ↑

Assume you have the following class definition,

class ShoppingBasket < ActiveRecord::Base

  def initialize(items = [])
    self.items = items
  end

end

then Excellent will report the problems in this piece of code:

$ excellent shopping_basket.rb 

  Excellent result:

  test.rb
    * Line   1: ShoppingBasket does not validate any attributes.
    * Line   1: ShoppingBasket defines initialize method.
    * Line   1: ShoppingBasket does not specify attr_accessible.

  Found 3 warnings.

To analyse all the models in your Rails application, just do

excellent app/models

in your RAILS_ROOT. You can also invoke analysation through the Simplabs::Excellent::Runner class. Excellent can also produce HTML output. To get a formatted HTML report, just specify html:<filename>:

excellent -o out.html app/models

You can also use Excellent in a Rake task:

require 'simplabs/excellent/rake'

Simplabs::Excellent::Rake::ExcellentTask.new(:excellent) do |t|
  t.html  = 'doc/excellent.html' # optional, if you don't specify html, output will be written to $stdout
  t.paths = %w(app lib)
end

Static analysis¶ ↑

A few words regarding static code analysis: Static code analysis tools like Excellent can never really understand the code. They just search for patterns that might inidicate problematic code. The word might really has to be stressed here since static analysis will usually return a reasonable number of false positives. For example, there might be pretty good reasons for empty rescue blocks that suppress all errors (Excellent itself does it). So, don’t try and code with the aim of passing Excellent with zero warnings. That will most likely make your code a mess. Instead use Excellent as a helper to find possibly problematic code early.

Contribute¶ ↑

If you want to contribute, just fork the repo. Also I would appretiate suggestions for more checks (especially Rails specific checks) - simply open a new issue: github.com/simplabs/excellent/issues.

Author¶ ↑

Excellent was inspired by roodi (github.com/martinjandrews/roodi), reek (github.com/kevinrutherford/reek) and flog (github.com/seattlerb/flog).