rails_best_practices: A Static Code Metric Tool for Rails Projects

What rails_best_practices Checks and Who Should Use It

rails_best_practices is a code metric tool for Rails codebases. It reads source files and reports violations of conventions that the Rails community has documented over time. The checks include things that are easy to miss in code review: a finder method placed in a controller instead of a model, a missing database index on a foreign key column, a before_filter that has been inlined in too many actions, or an unused helper method.

The default configuration in rails_best_practices.yml names over 30 individual check classes. A few examples: AlwaysAddDbIndexCheck flags foreign key columns that lack a database index; LawOfDemeterCheck flags method chains that reach through multiple objects; MoveFinderToNamedScopeCheck suggests replacing a repeated finder condition with a named scope; NeedlessDeepNestingCheck flags routes or controller logic nested more than two levels deep; and RemoveUnusedMethodsInControllersCheck, RemoveUnusedMethodsInHelpersCheck, and RemoveUnusedMethodsInModelsCheck each flag dead code in their respective layers. Several checks are disabled in the default configuration but available, including CheckSaveReturnValueCheck and UseBeforeFilterCheck.

The README states that the tool supports three ORM/ODMs: ActiveRecord, Mongoid, and MongoMapper. Template engines supported are ERB, Haml, Slim, and RABL. The tool supports Ruby 1.9.3 or newer.

The intended users are Rails developers and teams that want automated, static analysis of their Rails code. It works best as a complement to a test suite and code review process, not as a replacement for either. Running it takes seconds and produces a list of file paths and line numbers that point to specific convention violations.

How the Analysis Works: Static Parsing Across Controllers, Models, and Views

rails_best_practices parses Ruby source files, view templates, and route files statically without running the application. It applies a configurable set of check classes to the parsed AST and reports violations as a list of path-plus-line-number entries.

By default, the tool excludes the vendor, spec, test, and features directories from analysis. This is because those directories typically contain test code and third-party code rather than the application code you want to check. You can override this with the --vendor, --spec, --test, and --features flags, each of which opts one of those excluded directories back into analysis. To exclude a specific path such as db/migrate, pass the -e flag:

rails_best_practices -e "db/migrate" .

Multiple paths can be excluded by separating them with commas: -e "db/migrate,vendor". To run checks against only certain files, use the -o flag with a regexp pattern.

The README documents two output formats: plain text output on stdout, and HTML output with the -f html flag. The HTML output includes links that open the offending file directly in a text editor. The flags --with-textmate, --with-vscode, --with-sublime, and --with-mvim each configure which editor the HTML links open. When --with-git or --with-hg is set, the HTML output also displays the git commit and username for each violation, which is useful for tracking down when a violation was introduced. The --output-file flag saves the HTML report to a named file instead of the default output path. For quiet operation, --silent suppresses output except for the final count.

Installing and Running rails_best_practices

Install the gem globally or add it to the project's Gemfile:

gem install rails_best_practices

Or in the Gemfile:

gem "rails_best_practices"

To run the analysis from the root of a Rails project:

rails_best_practices .

To generate an HTML report:

rails_best_practices -f html .

If the gem is installed via Bundler from a GitHub source, the README instructs you to prefix the command with bundle exec:

bundle exec rails_best_practices .

If the tool throws a NoMethodError or syntax error, debug mode prints a stack trace along with the file that triggered it:

rails_best_practices -d .

To see all available options:

rails_best_practices -h

Customizing Which Checks Run with rails_best_practices.yml

The tool ships with a default set of enabled checks. To customize them, generate the configuration file first:

rails_best_practices -g

This produces a rails_best_practices.yml file at the project root. The default configuration lists more than 30 check classes, each as a YAML key with an options hash. Checks that are commented out are disabled by default, such as CheckSaveReturnValueCheck and LongLineCheck. You can enable them by uncommenting the line, and you can adjust numeric thresholds such as the line length limit:

LongLineCheck: { max_line_length: 80 }
MoveCodeIntoHelperCheck: { array_count: 3 }
MoveModelLogicIntoModelCheck: { use_count: 4 }

Each check also accepts an ignored_files option, which takes a regexp or array of regexps. For example:

DefaultScopeIsEvilCheck: { ignored_files: 'user\.rb' }

To run with a custom configuration file path:

rails_best_practices . -c config/rails_best_practices.yml

The README lists the full set of available check names, which cover areas such as database indexing, mass assignment, scope usage, helper complexity, route customization, and Law of Demeter compliance.

Limitations: Static Analysis Only, No Runtime Bugs, Limited ORM Support

rails_best_practices performs static analysis only. It does not run the application, so it cannot detect runtime errors, N+1 query problems in practice, or security vulnerabilities that depend on application state. It checks structural conventions, not runtime behavior.

The tool supports only three ORM/ODMs: ActiveRecord, Mongoid, and MongoMapper. If your project uses a different persistence layer, checks that rely on ORM-specific patterns may not apply or may produce false positives.

Some checks flag patterns that may be intentional. The DefaultScopeIsEvilCheck, for example, flags any use of default_scope in a model. There are legitimate use cases for default_scope, and the check cannot distinguish between a problematic default scope and a deliberate one. The ignored_files option allows you to suppress checks on specific files, but you must configure this manually.

The README also notes that the tool parses code using a Ruby parser. Files with unusual syntax or non-standard Ruby constructs may trigger parser errors that cause the tool to fail on that file.

Alternative: RuboCop

The most widely used alternative for Rails code analysis is RuboCop, which also performs thorough static analysis of Ruby code. RuboCop covers a broader set of checks than rails_best_practices, including style enforcement (line length, spacing, naming) and a dedicated rubocop-rails plugin for Rails-specific rules.

The key difference is scope. rails_best_practices focuses on Rails architecture conventions, things like where to place finder logic, when to extract a virtual attribute, and whether default_scope is being misused. RuboCop focuses more on Ruby style and code structure at the expression level.

A team might run both tools: RuboCop for style and Ruby idioms, rails_best_practices for architecture-level Rails conventions. They are not mutually exclusive and do not produce the same checks.

Editor Integration, CI, and Maintenance

The README documents integration with TextMate 2 via a bundle, and the --with-textmate, --with-vscode, --with-sublime, and --with-mvim flags enable direct file opening from the HTML report. For GitHub integration, --with-github GITHUB_NAME adds links that open files on GitHub.

For CI, the tool can be run as a command in any CI pipeline. It exits with a non-zero code when violations are found, which can be used to fail a CI step.

The last push to the repository was on 2026-04-23. The repository is not archived. There are no GitHub release tags. The repository is hosted at the GitHub URL listed in the README, and an accompanying website is referenced at rails-bestpractices.com.

Editorial conclusion

rails_best_practices is useful for Rails teams that want a fast, zero-configuration check against common convention violations. Run it at the project root and it reports issues immediately. It is not the right tool for detecting runtime bugs, security vulnerabilities, or performance regressions. The last push to the repository was on 2026-04-23. Before adopting it as part of a CI pipeline, verify that it supports the version of Ruby and the ORM your project uses, since ActiveRecord, Mongoid, and MongoMapper are the only supported ORM/ODMs.

Frequently asked questions

Official sources

1. flyerhzm/rails_best_practices on GitHub
2. Issues
3. License: MIT
4. Project website
5. README