Ruby style guide

This is a GitLab-specific style guide for Ruby code.

Generally, if a style is not covered by existing RuboCop rules or style guides, it shouldn't be a blocker. Before adding a new cop to enforce a given style, make sure to discuss it with your team. When the style is approved by a backend EM or by a BE staff eng, add a new section to this page to document the new rule. For every new guideline, add it in a new section and link the discussion from the section's version history note to provide context and serve as a reference.

Everything listed here can be reopened for discussion.

String literals quoting

Due to the sheer amount of work to rectify, we do not care whether string literals are single, or double quoted.

Previous discussions include:

Instance variable access using `attr_reader`

Introduced in GitLab 14.1.

Instance variables can be accessed in a variety of ways in a class:

# public
class Foo
  attr_reader :my_var

  def initialize(my_var)
    @my_var = my_var
  end

  def do_stuff
    puts my_var
  end
end

# private
class Foo
  def initialize(my_var)
    @my_var = my_var
  end

  private

  attr_reader :my_var

  def do_stuff
    puts my_var
  end
end

# direct
class Foo
  def initialize(my_var)
    @my_var = my_var
  end

  private

  def do_stuff
    puts @my_var
  end
end

Public attributes should only be used if they are accessed outside of the class. There is not a strong opinion on what strategy is used when attributes are only accessed internally, as long as there is consistency in related code.

Newlines style guide

This style guide recommends best practices for newlines in Ruby code.

Rule: separate code with newlines only to group together related logic

# bad
def method
  issue = Issue.new

  issue.save

  render json: issue
end

# good
def method
  issue = Issue.new
  issue.save

  render json: issue
end

Rule: separate code and block with newlines

Newline before block

# bad
def method
  issue = Issue.new
  if issue.save
    render json: issue
  end
end

# good
def method
  issue = Issue.new

  if issue.save
    render json: issue
  end
end

Rule: Newline after block

# bad
def method
  if issue.save
    issue.send_email
  end
  render json: issue
end

# good
def method
  if issue.save
    issue.send_email
  end

  render json: issue
end

Exception: no need for newline when code block starts or ends right inside another code block

# bad
def method

  if issue

    if issue.valid?
      issue.save
    end

  end

end

# good
def method
  if issue
    if issue.valid?
      issue.save
    end
  end
end