STYLE_GUIDE.md

Style Guide

In datarockets we enforce a community Ruby Style Guide.

Also, we have some new rules for writing Rails applications and Rspec test. You can find it by next links:

• Rails Style Guide
• Rspec Style Guide

This is a small list of differences which we have when compared with community style guide:

Table of contents

• Bundler
• Style
• Rspec

Bundler

• A Gem's requirements should be listed only once in a Gemfile. ^[link]

• Gems should be alphabetically sorted within groups. Also, you can use a line comment as a group separator. ^[link]

Style

• Limit lines to 120 characters. ^[link]

• Adopt a consistent string literal quoting style. ^[link]

• Avoid using nested interpolation. ^[link]

# bad
"Hello, #{user.blank? ? 'guest' : "dear #{user.name}"}"

# good
user_name = user.blank? ? 'guest' : "dear #{user.name}"
"Hello, #{user_name}"

• If elements of a hash literal span more than one line, we're aligning them by keys. Also, the first hash key is aligned by an indentation level. ^[link]

# bad
{
  foo: bar,
   ba: baz
}

{
  foo: bar,
  ba:  baz
}

{
    foo: bar,
  ba: baz
}

{
  foo: {
         bar: bar,
         ba: baz
       }
}

method_call({
               its_like: :this
             })

# good
{
  foo: bar,
  ba: baz
}

{
  foo: {
    bar: bar,
    ba: baz
  }
}

method_call({
  no: :difference
})

• All arguments on a multi-line method definition are aligning by an indentation level. This rule works as for keyword arguments, as for usual arguments. ^[link]

# bad
do_something(foo: 1,
             bar: 2)

# good
do_something(foo: 1,
  bar: 2)

# good
foo :bar,
  :baz

# bad
foo :bar,
    :baz

• The parameters on a multi-line method call or definition are aligning by an indentation level. ^[link]

  Recommended: write each parameter on the separate line.

# bad

def foo(bar, baz,
        kek, lol)
  123
end

# bad

def foo(
  bar,
     baz)
  123
end

# good

def foo(bar, baz,
  kek, lol)
  123
end

# better

def foo(
  bar,
  baz,
  kek,
  lol
)
  123
end

• The elements of a multi-line array are aligning by an indentation level. ^[link]

# bad

array = [1, 2, 3,
         4, 5, 6]

# bad

array = [1, 2, 3,
      4, 5, 6]

# good

array = [1, 2, 3,
  4, 5, 6]

• The indentation of the method name part in method calls that span more than one line are aligning by an indentation level. ^[link]

# bad
while myvariable
      .b
  # do something
end

# bad
Thing.a
     .b
     .c

# good
while myvariable
  .b

  # do something
end

# good
Thing.a
  .b
  .c

• The end shall be aligned with the left-hand-side of the variable assignment. But we prefer not to use code blocks with end for variable assignment and prefer move it into the separate methods. ^[link]

# bad

variable = if true
           end

variable = array.map do |value|
                    value
                  end

# good

variable = if true
end

variable =
  if true
  end

variable = array.map do |value|
  value
end

# better

variable = condition_value

def condition_value(*args)
  if true
  end
end

variable = values_from_array(array)

def values_from_array(array)
  array.map do |value|
    value
  end
end

• We're preferring a ruby style for methods indentations, not rails. You can check it here. ^[link]

# bad
class A
  def test
    puts "hello"
     puts "world"
  end
end

# bad
class A
  def test
    puts "hello"
    puts "world"
  end

  protected

    def foo
    end

  private

    def bar
    end
end

# good
class A
  def test
    puts "hello"
    puts "world"
  end
end

# good
class A
  def test
    puts "hello"
    puts "world"
  end

  protected

  def foo
  end

  private

  def bar
  end
end

• For hash literals not to add spaces after { or before }. We want to have the advantage of adding visual difference between block and hash literals. ^[link]

# bad
h = { a: 1, b: 2 }
Array.new(3) {|i| i + 1}

# good
h = {a: 1, b: 2}
Array.new(3) { |i| i + 1 }

• Use error as a variable name on processing exceptions. ^[link]

# bad
begin
  # do something
rescue MyException => e
  # do something
end

# good
begin
  # do something
rescue MyException => error
  # do something
end

• Write empty methods in an expanded way. ^[link]

# bad
def foo(bar); end

def self.foo(bar); end

# good
def foo(bar)
end

def self.foo(bar)
end

• Use leading underscores in cached instance variable name. ^[link]

# bad
def foo
  @something ||= calculate_expensive_thing
end

# bad
def foo
  @foo ||= calculate_expensive_thing
end

# good
def foo
  @_foo ||= calculate_expensive_thing
end

• Requires a comma after the last argument, but only for parenthesized method calls where each argument is on its own line. ^[link]

# bad
method(1, 2,)

# good
method(1, 2)

# bad
method(
  1, 2,
  3,
)

# good
method(
  1, 2,
  3
)

# bad
method(
  1, 2, 3,
)

# good
method(
  1, 2, 3
)

# good
method(
  1,
  2,
)

• Requires a comma after last item in an array, but only when each item is on its own line. ^[link]

# bad
a = [1, 2,]

# good
a = [1, 2]

# bad
a = [
  1, 2,
  3,
]

# good
a = [
  1, 2,
  3
]

# bad
a = [
  1, 2, 3,
]

# good
a = [
  1, 2, 3
]

# good
a = [
  1,
  2,
]

• Requires a comma after the last item in a hash. ^[link]

# bad
a = { foo: 1, bar: 2, }

# good
a = { foo: 1, bar: 2 }

# bad
a = {
  foo: 1, bar: 2,
  qux: 3,
}

# good
a = {
  foo: 1, bar: 2,
  qux: 3
}

# bad
a = {
  foo: 1, bar: 2, qux: 3,
}

# good
a = {
  foo: 1, bar: 2, qux: 3
}

# good
a = {
  foo: 1,
  bar: 2,
}

• There are not any required rules for frozen_string_literal magic url. Set up this cop depends on the project. So set up it on the local rubocop config manually. ^[link]