Ruby 💎

Hero image for Ruby 💎

Linting

The team uses RuboCop for automated code checks, and their guidelines largely comply with the default guidelines set by the analyzer.

Formatting

  • Use soft-tabs with a two space indent.
  • Limit each line of code to fewer than 130 characters.
  • Use a single empty line to break between statements to organize logical chunks of code.
  • End each file with a new line.

Naming

  • Use snake_case for symbols, methods and variables.

    :someSymbol
    someVar = 5
    
    def someMethod
      # some code
    end
    
    :some_symbol
    
    some_var = 5
    
    def some_method
      # some code
    end
    
  • Do not separate numbers from letters on symbols, methods and variables.

    :some_sym_1
    some_var_1 = 1
    
    def some_method_1
      # some code
    end
    
    :some_sym1
    
    some_var1 = 1
    
    def some_method1
      # some code
    end
    
  • Use CamelCase for classes and modules.

    class Someclass
      # some code
    end
    
    class Some_Class
      # some code
    end
    
    class SomeClass
      # some code
    end
    
  • Use snake_case for naming files.

    HelloWorld.rb
    
    hello_world.rb
    
  • Use snake_case for naming directories.

    lib/HelloWorld/hello_world.rb
    
    lib/hello_world/hello_world.rb
    
  • Aim to have just a single class/module per source file. Name the file name as the class/module, but replacing CamelCase with snake_case.

  • Use SCREAMING_SNAKE_CASE for other constants.

    SomeConst = 5
    
    SOME_CONST = 5
    
  • The names of predicate methods (methods that return a boolean value) should end in a question mark ?.

    def is_true
    end
    
    def true?
    end
    
  • The names of method which could raise exception should end in bang !.

    def authenticate
      raise UserNotAuthenticated unless authenticate_user(current_user)
    end
    
    def authenticate!
      raise UserNotAuthenticated unless authenticate_user(current_user)
    end
    

Syntax

  • Use the proc invocation shorthand when the invoked method is the only operation of a block.

    names.map { |name| name.upcase }
    
    names.map(&:upcase)
    
  • Prefer {...} over do...end for single-line blocks. Avoid using {...} for multi-line blocks.

    names = %w[Bozhidar Steve Sarah]
    
    names.each do |name|
      puts name
    end
    
    names.each { |name| puts name }
    
  • Use .call explicitly when calling lambdas.

    lambda.(x, y)
    
    lambda.call(x, y)
    
  • Use ... operator when forwarding method arguments to a method.

    def call(*args, **kwargs, &block)
      process(*args, **kwargs, &block)
    end
    
    def call(...)
      process(...)
    end
    

    Ruby 3.0 has added support passing leading arguments along with ... operator which allows writing more flexible methods.

    def create_github_repo(project_type, ...)
      if project_type == 'open_source'
        initialize_public_repo(...)
      else
        initialize_private_repo(...)
      end
    end
    
  • When defining an object of any mutable type meant to be a constant, make sure to call freeze on it. Common examples are strings, arrays, and hashes.

    class Color
      RED = 'red'
      BLUE = 'blue'
      GREEN = 'green'
    
      ALL_COLORS = [
        RED,
        BLUE,
        GREEN,
      ]
    
      COLOR_TO_RGB = {
        RED => 0xFF0000,
        BLUE => 0x0000FF,
        GREEN => 0x00FF00,
      }
    end
    
    class Color
      RED = 'red'.freeze
      BLUE = 'blue'.freeze
      GREEN = 'green'.freeze
    
      ALL_COLORS = [
        RED,
        BLUE,
        GREEN,
      ].freeze
    
      COLOR_TO_RGB = {
        RED => 0xFF0000,
        BLUE => 0x0000FF,
        GREEN => 0x00FF00,
      }.freeze
    end
    

Conditional Expressions

  • Never negate the conditional of an if block. Use unless instead.

    if !false then
      #...
    end
    
    unless false
      #...
    end
    
  • Never use the return value of = in conditionals.

    if is_branded = array.include? 'brand'
      #...
    end
    
    is_branded = array.include? 'brand'
    
    if is_branded
      #...
    end
    
  • Prefer using guard clauses over if/else and ternary operators.

    def message
      if valid?
        'success'
      else
        'error'
      end
    end
    
    def message
      valid? ? 'success' : 'error'
    end
    
    def message
      return 'success' if valid?
    
      'error'
    end
    
  • Never use nested conditionals for flow of control.

    The general principles boil down to:

    • Return immediately if the function cannot do anything more.
    • Reduce nesting and indentation in the code by returning early. This makes the code easier to read and requires less mental bookkeeping on the part of the reader to keep track of else branches.
    • The core or most important flows should be the least indented.
    def compute
      server = find_server
      if server
        client = server.client
        if client
          request = client.make_request
          if request
            process_request(request)
          end
        end
      end
    end
    
    def compute
      server = find_server
      return unless server
    
      client = server.client
      return unless client
    
      request = client.make_request
      return unless request
    
      process_request(request)
    end
    

    Refer to the section “Guard Clause”, p68-70 in Beck, Kent. Implementation Patterns. Upper Saddle River: Addison-Wesley, 2008.

Collections

  • Prefer %w to the literal array syntax for an array of raw strings.

    STATES = ['draft', 'open', 'closed']
    
    # Less Preferred
    STATES = %w(draft open closed)
    
    STATES = %w[draft open closed]
    
  • Use symbols instead of strings as hash keys.

    hash = { 'one' => 1, 'two' => 2, 'three' => 3 }
    
    hash = { one: 1, two: 2, three: 3 }
    
  • Use Hash#key? instead of Hash#has_key? and Hash#value? instead of Hash#has_value?. According to Matz, the longer forms are considered deprecated.

    hash.has_key?(:test)
    hash.has_value?(value)
    
    hash.key?(:test)
    hash.value?(value)
    

Strings

  • Prefer single quotes over double quotes.

    ruby = "Ruby is an interpreted, high-level, general-purpose programming language."
    
    ruby = 'Ruby is an interpreted, high-level, general-purpose programming language.'
    
  • Prefer string interpolation over appending to strings.

    full_name = user.first_name + ' ' + user.last_name
    
    full_name = "#{user.first_name} #{user.last_name}"
    
  • Prefer symbols over strings where applicable.

    person = {
      'name' => 'Yukihiro Matsumoto',
      'age' => 55
    }
    
    person = {
      name: 'Yukihiro Matsumoto',
      age: 55
    }
    
    class User
      attr_accessor 'first_name'
      ...
    end
    
    class User
      attr_accessor :first_name
      ...
    end
    
  • Prefer heredoc to multiline strings.

    notice = "Subscription expiring soon!.\n Your free trial will expire in #{days_until_expiration} days.\n Please update your billing information."
    
    notice = <<~HEREDOC
      Subscription expiring soon!.
      Your free trial will expire in #{days_until_expiration} days.
      Please update your billing information.
    HEREDOC
    
  • Use format when formatting string to a certain format.

    formatted_card_number = "#{card_brand} ******#{card_last_digits}"
    
    CARD_NUMBER_FORMAT = '%{card_brand} ******%{card_last_digits}'.freeze
    
    formatted_card_number = format(CARD_NUMBER_FORMAT, card_brand: card_brand, card_last_digits: card_last_digits)
    

Methods

  • Use parentheses in method definitions only if it accepts any parameters.

    def method_without_params
      # body omitted
    end
    
    def method_with_parameters(param1, param2)
      # body omitted
    end
    
  • Avoid usage of positional arguments. Use keyword arguments or an options hash instead.

    def positional_method(a = 1, b = 2, c, d)
      # method body
    end
    
    def method_with_keyword_arguments(a:, b:, c:, d:)
    end
    
    def method_with_options(options = {})
    end
    
  • Use endless method for writing single liner method (This convention only applicable for Ruby 3 or later).

    def square(x)
      x * x
    end
    
    def square(x) = x * x
    

Modules

  • Use modules to organize a chunk of common stateless operations.

  • Use :: only to reference constants and constructors. Do not use :: for regular method invocation.

    Klass::some_method
    object::some_method
    
    Klass.some_method
    object.some_method
    
  • Properly choose between def self, extend self and module_function.

Let’s consider a module Math implementing a method pi.

Use def self.pi

include Math will not give any sort of accessor to .pi, not YourClass.pi, not instance.pi, nothing. Use Math.pi instead.

Use extend self with public methods

include Math will give instances a public instance method .pi.

Use extend self with private methods

include Math will give a private instance method .pi but Math.pi will say “private method pi called”

Use module_function :pi

include Math will give instances a private .pi method and Math.pi still works just fine.

Classes

  • Code in Ruby classes must follow the following structure:

    # requires
    require 'dependency_filename'
    
    class KlassName
      # extend and include
      extend SomeModule
      include AnotherModule
    
      # constants
      SOME_CONSTANT = '20'.freeze
    
      # attribute macros
      attr_reader :name
    
      # additional macros (if any)
      validates :name
    
      # public class methods
      class << self
        def some_method
          #...
        end
      end
    
      # initialization
      def initialize
      end
    
      # public instance methods
      def some_method
      end
    
      # Group alias methods at the end of public methods
      alias alias_name some_method
      alias alias_alternative_name some_method
    
      # protected methods
      protected
    
      def some_protected_method
      end
    
      # private methods
      private
    
      def some_private_method
      end
    end
    
  • Avoid nesting multiple classes within classes. Instead maintain each in their own file in a folder named like the containing class.

    
    # parent.rb
    class Parent
      class Child
      end
    end
    
    
    # parent.rb
    class Parent
    end
    
    # parent/child.rb
    class Parent
      class Child
      end
    end
    
  • Classes should be used only when it makes sense to create instances out of them. Prefer modules to classes with only class methods.

    class SomeClass
      class << self
        def self.some_method
          #...
        end
    
        def self.some_other_method
          #...
        end
      end
    end
    
    module SomeModule
      def some_method
        #...
      end
    
      def some_other_method
        #...
      end
    end
    
  • Use class << self to define class methods instead of self..

    class SomeKlass
      def self.method_name
        #...
      end
    end
    
    class SomeKlass
      class << self
        def method_name
          #...
        end
      end
    end
    
  • Try to make the classes as SOLID as possible.

  • Use the attr family of functions to define trivial accessors.

    class Klass
      def initialize(a, b)
        @a = a
        @b = b
      end
    
      def a
        @a
      end
    
      def b
        @b
      end
    end
    
    class Klass
      attr_reader :a, :b
    
      def initialize(a, b)
        @a = a
        @b = b
      end
    end
    

Exceptions

  • Never rescue the Exception class. Rescue specific error classes.

    begin
      1/0
    rescue Exception
      # exception handling
    end
    
    begin
      1/0
    rescue ZeroDivisionError
      # exception handling
    end
    

Monkey Patching/Refinements

  • Avoid monkey patching built-in classes, use refinements instead

    class Hash
      def deep_transform_camelize_keys
        deep_transform_keys { |key| key.to_s.camelize(:lower) }
      end
    end
    
    module HashExtensions
      refine Hash do
        def deep_transform_camelize_keys
          deep_transform_keys { |key| key.to_s.camelize(:lower) }
        end
      end
    end