rails_best_practices: a static checker for Rails code quality

What rails_best_practices checks, and who it is for

The README describes rails_best_practices as "a code metric tool to check the quality of Rails code". That wording matters. It is not a linter in the RuboCop sense and not a formatter. It walks a Rails application tree, applies a fixed catalogue of named checks, and prints the files and line numbers where those checks fire.

The checks are structural rather than stylistic. The default configuration lists entries such as AlwaysAddDbIndexCheck, LawOfDemeterCheck, RemoveUnusedMethodsInModelsCheck, MoveCodeIntoControllerCheck and NotUseDefaultRouteCheck. Several of them take parameters: MoveCodeIntoHelperCheck uses array_count: 3, MoveModelLogicIntoModelCheck uses use_count: 4, NeedlessDeepNestingCheck uses nested_count: 2. Those thresholds are the whole point of the tool. A method that touches four model operations is flagged; one that touches three is not.

The audience is a team that already has tests and a style linter and still wants a second opinion on Rails-specific structure. The tool supports activerecord, mongoid and mongomapper for persistence, and erb, haml, slim and rabl for templates, so it is not limited to ActiveRecord or ERB applications. It requires Ruby 1.9.3 or newer, which is a low floor and suggests the project has been around long enough that its checks encode older Rails conventions. Nothing in the README suggests the check catalogue is extensible from user code, so the practical scope is the shipped set plus the parameters you set in YAML.

How the analysis works: files in, findings out

The mechanism is directory scanning plus rule evaluation. You point the tool at the root of a Rails app, and it parses the Ruby and template files it finds, then runs each enabled check over the parsed representation. Findings are reported with file and line information.

Two details in the README shape the results more than any single check. First, the default scope is wider than most people expect: rails_best_practices will parse code in the vendor, spec, test and features directories unless told otherwise. Second, the output is plain text by default, with an HTML mode available through -f html. There are also --silent and --without-color flags for console runs, which are the ones you would use in a script where you only care about the exit path.

The HTML mode is where the tool gets more interesting than a grep. Options such as --with-git and --with-hg add commit and username information to the HTML report, and --with-github takes a repository name or a full URL and links findings back to the host. There are also --with-vscode, --with-textmate, --with-sublime and --with-mvim flags that turn findings into editor-opening links. In practice this means the report can be handed to a reviewer as a navigable page rather than a wall of console text. The template used for that page can be replaced with --template, and the result written with --output-file. One caveat: the editor and version-control integrations are documented as HTML-only features, so they are not available in a plain terminal run.

Installing the gem and running a first scan

The README gives two install paths. The direct one is a gem install. The other is adding it to a Gemfile, which is what most applications will do.

gem install rails_best_practices

Or, in the Gemfile:

gem "rails_best_practices"

At the root directory of a Rails app, the basic invocation is a path argument. A single dot means the current directory. Expect a list of findings, each naming a check, a file and a line.

rails_best_practices .

For an HTML report instead of console output:

rails_best_practices -f html .

If the gem is installed through Bundler, particularly from a GitHub source, the README says to prefix the command with bundle exec:

bundle exec rails_best_practices .

Because the default scan includes vendor, spec, test and features, a first run on a large app will be noisy. Excluding directories is done with -e or --exclude, and multiple patterns are comma-separated. The README's own example excludes migrations:

rails_best_practices -e "db/migrate" .

The exclusion flag accepts a comma-separated regexp list, and the related -o or --only flag restricts analysis to matching patterns, which is useful when you want to check one subsystem before committing to a full run. If the tool raises a NoMethodError or a syntax error, debug mode prints the stack trace and the source of the offending file:

rails_best_practices -d .

For a first pass on an unfamiliar codebase, the sensible sequence is a full run to see the shape of the output, then a second run with -e and -o narrowed to the directory you actually plan to fix.

Tuning the checks with rails_best_practices.yml

The default check set is not meant to be run as-is forever. The README's customization path starts with generating a configuration file:

rails_best_practices -g

That writes rails_best_practices.yml. The file the README shows contains roughly thirty entries in the form CheckName: { } or CheckName: { parameter: value }. Several are commented out in the default file, including CheckSaveReturnValueCheck, CheckDestroyReturnValueCheck, HashSyntaxCheck, LongLineCheck, RemoveTabCheck, UseBeforeFilterCheck and UseParenthesesInMethodDefCheck. Commenting a line out disables that check; uncommenting it enables it. A few checks accept an except_methods list, notably the three RemoveUnusedMethodsIn* checks.

Once the file exists, it is passed with -c. The default location is config/rails_best_practices.yml, so the flag is only needed when the file lives elsewhere:

rails_best_practices . -c config/rails_best_practices.yml

This is the part of the tool that demands judgement. A check like RemoveUnusedMethodsInControllersCheck is only as good as its ability to see every caller, and dynamic dispatch, metaprogramming or reflection can produce false positives. The except_methods option exists precisely because some methods cannot be proven unused by static reading. The commented-out entries in the generated file are a useful signal too: the project ships them disabled by default, which suggests the maintainers consider them either too noisy or too opinionated for a general audience. Treat the generated YAML as a starting draft, not a finished policy, and keep it in version control so changes to it are reviewable.

Where the tool falls short

The most concrete limitation is the default scope. Parsing vendor, spec, test and features directories by default means the first run on an established application will report findings in code you do not own or do not intend to change. You have to remember -e on every invocation, or encode it in whatever wrapper you build. The README does not document a way to set exclusions permanently in the configuration file, so this is a command-line concern rather than a project setting.

Second, the checks are heuristics with fixed thresholds. LawOfDemeterCheck and the Move* family will flag code that a human reviewer would accept, and the parameters in the YAML are the only lever. There is no suppression comment mechanism described in the README, so silencing a single false positive means either disabling the check globally or adding the method to an except_methods list where one exists. That is a coarse instrument on a large codebase.

Third, this is a Rails-shaped tool. It is not useful for a plain Ruby library, a Sinatra app or a non-Ruby project, and it says nothing about security, dependency vulnerabilities or runtime performance. If your actual problem is that a controller action is slow, this tool will not tell you. It also will not fix anything: the README describes analysis and reporting only, with no autocorrect path. A team looking for automatic remediation will be disappointed.

The README also does not document rollback, versioning policy or a deprecation process for checks, so a team that pins the gem and later upgrades should read the CHANGELOG.md in the repository rather than expect guidance in the README.

How it differs from RuboCop and from the Rails style guide

The obvious alternative in a Rails project is RuboCop, usually with rubocop-rails. The difference is the unit of analysis. RuboCop works file by file against syntactic and stylistic rules: indentation, method length, string quoting, and with the Rails extension, things like preferring find_by over where(...).first. rails_best_practices works across files and asks structural questions that a single-file linter cannot answer well: is this model method called anywhere, does this association have a matching database index, does this controller action reach through too many objects.

That cross-file view is also why the two tools produce different kinds of noise. RuboCop findings are usually local and easy to fix mechanically, and RuboCop has an autocorrect mode for many of them. rails_best_practices findings often require a design decision: move this logic into a model, add an index, delete a method that may be called from a place the parser cannot see. The Rails style guide, by contrast, is documentation rather than an executable check; it states conventions and leaves enforcement to a human or a separate tool, so it cannot fail a build.

There is also a scope difference worth naming. RuboCop and the style guide both cover general Ruby style, which applies to gems, scripts and Rake tasks. rails_best_practices is concerned with the structure of a Rails application specifically, which is why its checks reference models, controllers, helpers, migrations and routes. If you already run RuboCop and want the structural checks, the two can coexist, but expect to spend real time tuning rails_best_practices.yml before its output is actionable.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-04-23. That is recent enough that the project is not dormant, but the README does not describe a release cadence, and the repository has no published releases, so pinning a version and reading the CHANGELOG.md at the repository root before upgrading is the practical approach.

The licence is MIT, which is permissive and places few obligations on how you use the gem inside a commercial application. This is not legal advice; if your organisation has specific requirements around attribution or bundled dependencies, check the MIT_LICENSE file in the repository rather than relying on a summary.

The upgrade cost is mostly configuration churn. Because checks are named entries in rails_best_practices.yml and several carry parameters, a new version that adds, renames or re-thresholds a check can change your finding count without any change to your code. Keeping the generated YAML in version control and diffing it after a gem bump is the cheapest way to see that happen. The Ruby version floor of 1.9.3 in the README is old enough that it tells you little about which modern Rails releases the checks were written against, so a jump across major Rails versions is the moment to re-read the check list rather than assume the thresholds still fit.

Editorial conclusion

Adopt rails_best_practices if you maintain a Rails codebase and want a cheap, repeatable pass over structural smells such as missing indexes or unused controller methods. Do not adopt it expecting a formatter, a security scanner or a replacement for tests; it reports code metric findings, and the default run also parses vendor, spec, test and features directories unless you exclude them. Before wiring it into CI, run rails_best_practices -g to generate rails_best_practices.yml, comment out the checks your team will not act on, and confirm which of the roughly thirty checks fire on your tree.

Frequently asked questions

Official sources

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