Table of Contents

About the style guide

This Ruby style guide recommends best practices so that real-world Ruby
programmers can write code that can be maintained by other real-world Ruby
programmers. A style guide that reflects real-world usage gets used, and a
style guide that holds to an ideal that has been rejected by the people it is
supposed to help risks not getting used at all – no matter how good it
is.

This guide is largely based upon Bozhidar Batsov’s
Ruby Style Guide, based on feedback and suggestions from
members of the Ruby community and various highly regarded Ruby programming
resources, such as Programming Ruby 1.91 and
The Ruby Programming Language2.

Formatting

Nearly everybody is convinced that every style but their own is
ugly and unreadable. Leave out the “but their own” and they’re
probably right…

– Jerry Coffin (on indentation)

Indent with spaces

Use UTF-8 as the source file encoding. Use two spaces per indentation level. No hard tabs.

Line endings

Use Unix-style line endings (BSD/Solaris/Linux/OSX users are covered by
default, Windows users have to be extra careful). You can add the following git
configuration setting to protect your project from Windows line
endings creeping in:

$ git config --global core.autocrlf true

Avoid trailing whitespace at the end of lines.

Separating statements and expressions

Don’t use ; to separate statements and expressions. As a corollary - use one
expression per line.

# badputs'foobar';# superfluous semicolonputs'foo';puts'bar'# two expression on the same line# goodputs'foobar'puts'foo'puts'bar'puts'foo','bar'# this applies to puts in particular

Avoid single-line methods. Although they are somewhat popular in the wild,
there are a few peculiarities about their definition syntax that make their use
undesirable. At any rate - there should be no more than one expression in a
single-line method.

# baddeftoo_much;something;something_else;end# okish - notice that the first ; is requireddefno_braces_method;bodyend# okish - notice that the second ; is optionaldefno_braces_method;body;end# okish - valid syntax, but no ; make it kind of hard to readdefsome_method()bodyend# gooddefsome_methodbodyend

One exception to the rule are empty-body methods.

# gooddefno_op;end

Spaces around symbols

Use spaces around operators, after commas, colons and semicolons, around {
and before }. Whitespace might be (mostly) irrelevant to the Ruby
interpreter, but its proper use is the key to writing easily readable code.

sum=1+2a,b=1,21>2?true:false;puts'Hi'[1,2,3].each{|e|putse}

The only exception, regarding operators, is the exponent operator:

# bade=M*c**2# goode=M*c**2

No spaces after (, [ or before ], ).

some(arg).other[1,2,3].length

{ and } deserve a bit of clarification, since they are used for block and
hash literals, as well as embedded expressions in strings. For hash literals
two styles are common:

# less readable{one: 1,two: 2}# better{one: 1,two: 2}

The second variant is slightly more readable (and arguably more popular in the
Ruby community in general) and should be used over the first.

As far as embedded expressions go, there are also two common options:

# ok"string#{expr}"# better - no spaces"string#{expr}"

The second style is more popular and should be preferred.

Use spaces around the = operator when assigning default values to method
parameters:

Empty lines

Use empty lines between defs and to break up a method into logical
paragraphs. Using two empty lines between methods is also recommended for
visually distinguishing them from individual sections of a particular method:

Avoid line continuation \ where not required. In practice, avoid using line
continuations at all.

# badresult=1-\2# good (but still ugly as hell)result=1\-2

Optimise readability

Add underscores to large numeric literals to improve their readability.

# bad - how many 0s are there?num=1000000# good - much easier to parse for the human brainnum=1_000_000

Limit lines to 100 characters, but try to keep them inside 80 characters where possible. This restriction is intended to encourage vertical readability3 rather than simply to make text fit inside a smaller editor window.

Documentation

Use YARD and its conventions for API documentation. Don’t put an empty line
between the comment block and the def.

Comments

Don’t use block comments. They cannot be preceded by whitespace and are not as
easy to spot as regular comments.