Shopify's Ruby Style Guide: the rules and the RuboCop config that enforces them

A style guide with a machine-readable form

Shopify's Ruby Style Guide is described as a loose coding style to follow while developing in Ruby, and the document opens with the reasoning rather than the rules. Ruby is the main language at Shopify, the company describes itself as primarily a Ruby shop and probably one of the largest, and the guide says the language is the go-to for new web projects and scripting. It also expects every developer there to have at least a passing understanding of Ruby, on the grounds that it will make you a better developer whatever you work in day to day.

The lineage is stated plainly. The guide is the result of over a decade of Ruby development at Shopify, and much of its content is based on Bozhidar Batsov's Ruby Style Guide, adapted to Shopify by many contributors.

What makes it more than a document is the adoption path. The project recommends using RuboCop to help teams adopt the guide, and offers a default RuboCop configuration you can inherit from so that you stay in sync with the guide itself. The mechanism is a gem:

gem "rubocop-shopify", require: false

and then, at the top of your project's RuboCop configuration file:

inherit_gem:
  rubocop-shopify: rubocop.yml

Any Include or Exclude configuration you provide is merged with RuboCop's defaults, and the project points at RuboCop's own documentation for the details of inheriting configuration from a dependency gem.

So the guide is a convention and the gem is the enforcement. That split is the design, and it explains the repository layout, which contains a .rubocop.yml, a rubocop.yml, a rubocop-shopify.gemspec, a Gemfile with a gemfiles/ directory for testing against multiple dependency sets, a Rakefile, a test/ directory, an integration.md, and the lib/ directory holding the published gem.

General rules that read like a list of past mistakes

The General section is short, and every item in it is a lesson rather than an aesthetic preference.

Make all lines of a method operate on the same level of abstraction, which the guide names as the Single Level of Abstraction Principle. Code in a functional way and avoid mutation where you can. Avoid mutating arguments. Avoid monkeypatching. Avoid long methods and long parameter lists. Avoid needless metaprogramming. Prefer public_send over send so as not to circumvent private and protected visibility. Write ruby -w safe code. Avoid more than three levels of block nesting.

One item carries a quotation and a link, and it is the most interesting of the set. The guide says to avoid defensive programming, with an archived Erlang programming rules page as the reference and a note that overly defensive programming may safeguard against errors that will never be encountered, thus incurring run-time and maintenance costs.

That is a strong position to take in a document that most companies use to increase the amount of code in a codebase. A shop that has run Ruby in production for ten years accumulates a great deal of paranoia about nil and about exceptions, and a style guide that pushes back on that is arguing from experience rather than taste. The counter-argument is equally real: a defensive check can be the difference between a 500 and a helpful message, and the guide does not say which errors are worth catching, so the judgement stays with the reader.

The absence of an explicit section on thread safety, on frozen string literals, or on any particular testing style is also telling. The guide is about form, not about architecture, and the sections that follow are the same kind of thing: layout, syntax, naming, classes and modules, exceptions, collections, strings, regular expressions, percent literals and testing.

Layout rules that a linter can mostly check for you

The Layout section is the largest, and it is the section where the value of the RuboCop config is clearest, because these are mechanical rules.

The basics: UTF-8 source encoding, 2 space indent and no tabs, Unix line endings, and one expression per line rather than separating statements with semicolons. Spacing is specified in detail: spaces around operators, after commas, colons and semicolons, around curly braces, and no space after the bang operator or inside range literals. Method call operators take no surrounding space, so foo . bar is wrong and foo.bar is right.

Indentation has its own rules that Ruby programmers argue about, and the guide takes a position on each. Indent when as deep as the case line. When assigning the result of a conditional expression to a variable, align the branches with the variable that receives the return value. When assigning the result of a begin block, align rescue, ensure and end with the start of the line. Align the parameters of a multi-line method call one level of indentation relative to the start of the line with the method call, and when chaining methods on multiple lines, indent successive calls by one level of indentation. Align the elements of array literals spanning multiple lines.

Then there are the limits and the hygiene rules: lines are limited to 120 characters, trailing whitespace is avoided, extra whitespace is avoided except for alignment purposes, and every file ends with a newline. Block comments are discouraged in favour of line comments, and the closing method call brace goes on the line after the last argument when the opening brace is on its own line.

The rule about wrapping a method call, hash or array over multiple lines has a documented set of special cases, including a single argument method call, a last argument that is itself multiline, and a single value array. Those exceptions are the part a linter cannot infer, and they are exactly the part a style guide has to spell out.

The repository as a test harness for the guide

The tree tells you more about how this project is validated than the readme does.

There is a Gemfile and a Gemfile.lock, a .ruby-version file, a gemfiles/ directory, and a test/ directory. The gemfiles/ directory is a standard pattern for a gem that needs to be tested against several dependency sets, and it is how the config gets checked against more than one version of RuboCop. There is a Rakefile driving those runs, and an integration.md documenting the integration side of the project.

There is also a .devcontainer/ directory, so a contributor can work in a container with the right Ruby version rather than matching it locally, and a .github/ directory for the automation. A CNAME file sits at the root, which is the GitHub Pages custom domain file, and _config.yml, _includes/, _layouts/, css/, images/ and config/ are the Jekyll site that renders the guide at ruby-style-guide.shopify.dev.

The result is that the published document and the published gem are the same thing. The readme on GitHub is the guide with front matter, the site is the rendered version, and the rules in the prose are mirrored by the configuration in the gem. That is worth more than a prose guide, because a prose guide drifts and a linter does not.

The release history shows how the project moves. The recent tags are v3.1.0 on 2026-09-14, v3.0.2 on 2026-08-07 and v3.0.1 on 2026-07-14, so there was a 3.0 line in the summer of 2026 and a 3.1 point release in September. The last push to the repository was on 2026-10-14, so the working tree is ahead of the newest tag. For a project whose value is that it stays in sync with a RuboCop release, that cadence is the relevant signal: a guide that lags RuboCop by a year is a guide that does not get adopted.

Where the style guide is the wrong tool

The first limitation is that it is Shopify's guide, not yours. Every rule encodes a decision made in a codebase with particular constraints, a particular scale and particular people. The 120 character line limit and the no-mutation preference are defensible, but a team whose domain has deeply nested data structures, or whose Ruby runs in a memory-constrained environment where mutation is a deliberate optimisation, will hit friction. The guide says it is loose, which is generous phrasing for a document that a linter will enforce mechanically.

The second is that adopting it wholesale is usually a mistake even when you like it. Inheriting the whole rubocop-shopify configuration brings its rules into your codebase, and the practical result on an existing project is a large diff and a set of offences you have to either fix or configure away. The Include and Exclude merging behaviour helps, but it is still the case that a team adopting this usually wants to turn on the rules it agrees with first and add the rest as it goes.

The third is that a style guide does not cover the things that actually break projects. There is no guidance here on module boundaries, on when to extract a class, on testing strategy beyond a section heading, on error handling conventions or on dependency management. A guide that covers form and not structure leaves the hard decisions where they were, and the fact that the guide explicitly leaves the level of abstraction and the length of a method to judgement means it stops well short of design guidance.

The fourth is the coupling to RuboCop. The guide is implemented as RuboCop configuration, so adopting the style means adopting RuboCop, and it means a RuboCop version bump can change what the rules mean or which cops exist. A team that has reasons not to want a linter in the build, or that has standardised on a different linter, gets the prose without the enforcement, which is a significantly weaker artefact.

The fifth is that a guide is only as good as its adoption. The repository is the source of truth and the gem keeps you in sync with it, but nothing forces anyone to upgrade the gem. A style guide that is copied into a wiki page and never updated is worse than no guide, because it carries the authority of the original without the currency. The gem is the part worth taking.

Editorial conclusion

Shopify's style guide fits a Ruby team that has no agreed conventions of its own, because the rules arrive as a RuboCop configuration you inherit rather than as a document you have to argue about, and the maintainability argument for it is concrete since it is derived from a decade of production Ruby at a large shop. It is the wrong choice if your team has strong and different opinions, since the guide explicitly describes itself as loose, and it is the wrong choice for a project that does not want a linter in its build at all. Before adopting it, add the rubocop-shopify gem and inherit its configuration, read the General and Layout sections against your existing codebase, and note that the last push was on 2026-10-14 with version 3.1.0 published on 2026-09-14.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Shopify/ruby-style-guide on GitHub