hovancik/BSDSec

Classes and modules are the units of reuse and release. It is therefore considered good practice to annotate every class and module with a brief comment outlining its responsibilities.

Example

Given

class Dummy
  # Do things...
end

Reek would emit the following warning:

test.rb -- 1 warning:
  [1]:Dummy has no descriptive comment (IrresponsibleModule)

Fixing this is simple - just an explaining comment:

# The Dummy class is responsible for ...
class Dummy
  # Do things...
end

An Uncommunicative Variable Name is a variable name that doesn't communicate its intent well enough.

Poor names make it hard for the reader to build a mental picture of what's going on in the code. They can also be mis-interpreted; and they hurt the flow of reading, because the reader must slow down to interpret the names.

Checks if empty lines around the bodies of classes match the configuration.

Example: EnforcedStyle: noemptylines (default)

# good
 
class Foo
  def bar
    # ...
  end
end

Example: EnforcedStyle: empty_lines

# good
 
class Foo
 
  def bar
    # ...
  end
 
end

Example: EnforcedStyle: emptylinesexcept_namespace

# good
 
class Foo
  class Bar
 
    # ...
 
  end
end

Example: EnforcedStyle: emptylinesspecial

# good
class Foo
 
  def bar; end
 
end

Example: EnforcedStyle: beginning_only

# good
 
class Foo
 
  def bar
    # ...
  end
end

Example: EnforcedStyle: ending_only

# good
 
class Foo
  def bar
    # ...
  end
 
end

Checks if empty lines around the bodies of classes match the configuration.

Example: EnforcedStyle: noemptylines (default)

# good
 
class Foo
  def bar
    # ...
  end
end

Example: EnforcedStyle: empty_lines

# good
 
class Foo
 
  def bar
    # ...
  end
 
end

Example: EnforcedStyle: emptylinesexcept_namespace

# good
 
class Foo
  class Bar
 
    # ...
 
  end
end

Example: EnforcedStyle: emptylinesspecial

# good
class Foo
 
  def bar; end
 
end

Example: EnforcedStyle: beginning_only

# good
 
class Foo
 
  def bar
    # ...
  end
end

Example: EnforcedStyle: ending_only

# good
 
class Foo
  def bar
    # ...
  end
 
end

Checks for indentation that doesn't use the specified number of spaces.

See also the IndentationConsistency cop which is the companion to this one.

Example:

# bad
class A
 def test
  puts 'hello'
 end
end
 
# good
class A
  def test
    puts 'hello'
  end
end

Example: AllowedPatterns: ['^\s*module']

# bad
module A
class B
  def test
  puts 'hello'
  end
end
end
 
# good
module A
class B
  def test
    puts 'hello'
  end
end
end

Checks for indentation that doesn't use the specified number of spaces.

See also the IndentationConsistency cop which is the companion to this one.

Example:

# bad
class A
 def test
  puts 'hello'
 end
end
 
# good
class A
  def test
    puts 'hello'
  end
end

Example: AllowedPatterns: ['^\s*module']

# bad
module A
class B
  def test
  puts 'hello'
  end
end
end
 
# good
module A
class B
  def test
    puts 'hello'
  end
end
end

Checks for indentation that doesn't use the specified number of spaces.

See also the IndentationConsistency cop which is the companion to this one.

Example:

# bad
class A
 def test
  puts 'hello'
 end
end
 
# good
class A
  def test
    puts 'hello'
  end
end

Example: AllowedPatterns: ['^\s*module']

# bad
module A
class B
  def test
  puts 'hello'
  end
end
end
 
# good
module A
class B
  def test
    puts 'hello'
  end
end
end

Checks for indentation that doesn't use the specified number of spaces.

See also the IndentationConsistency cop which is the companion to this one.

Example:

# bad
class A
 def test
  puts 'hello'
 end
end
 
# good
class A
  def test
    puts 'hello'
  end
end

Example: AllowedPatterns: ['^\s*module']

# bad
module A
class B
  def test
  puts 'hello'
  end
end
end
 
# good
module A
class B
  def test
    puts 'hello'
  end
end
end

Checks that block braces have or don't have surrounding space inside them on configuration. For blocks taking parameters, it checks that the left brace has or doesn't have trailing space depending on configuration.

Example: EnforcedStyle: space (default)

# The `space` style enforces that block braces have
# surrounding space.
 
# bad
some_array.each {puts e}
 
# good
some_array.each { puts e }

Example: EnforcedStyle: no_space

# The `no_space` style enforces that block braces don't
# have surrounding space.
 
# bad
some_array.each { puts e }
 
# good
some_array.each {puts e}

Example: EnforcedStyleForEmptyBraces: no_space (default)

# The `no_space` EnforcedStyleForEmptyBraces style enforces that
# block braces don't have a space in between when empty.
 
# bad
some_array.each {   }
some_array.each {  }
some_array.each { }
 
# good
some_array.each {}

Example: EnforcedStyleForEmptyBraces: space

# The `space` EnforcedStyleForEmptyBraces style enforces that
# block braces have at least a space in between when empty.
 
# bad
some_array.each {}
 
# good
some_array.each { }
some_array.each {  }
some_array.each {   }

Example: SpaceBeforeBlockParameters: true (default)

# The SpaceBeforeBlockParameters style set to `true` enforces that
# there is a space between `{` and `|`. Overrides `EnforcedStyle`
# if there is a conflict.
 
# bad
[1, 2, 3].each {|n| n * 2 }
 
# good
[1, 2, 3].each { |n| n * 2 }

Example: SpaceBeforeBlockParameters: false

# The SpaceBeforeBlockParameters style set to `false` enforces that
# there is no space between `{` and `|`. Overrides `EnforcedStyle`
# if there is a conflict.
 
# bad
[1, 2, 3].each { |n| n * 2 }
 
# good
[1, 2, 3].each {|n| n * 2 }

Checks for redundant uses of self.

The usage of self is only needed when:

• Sending a message to same object with zero arguments in presence of a method name clash with an argument or a local variable.

• Calling an attribute writer to prevent a local variable assignment.

Note, with using explicit self you can only send messages with public or protected scope, you cannot send private messages this way.

Note we allow uses of self with operators because it would be awkward otherwise.

Example:

# bad
def foo(bar)
  self.baz
end
 
# good
def foo(bar)
  self.bar  # Resolves name clash with the argument.
end
 
def foo
  bar = 1
  self.bar  # Resolves name clash with the local variable.
end
 
def foo
  %w[x y z].select do |bar|
    self.bar == bar  # Resolves name clash with argument of the block.
  end
end

Checks for missing top-level documentation of classes and modules. Classes with no body are exempt from the check and so are namespace modules - modules that have nothing in their bodies except classes, other modules, constant definitions or constant visibility declarations.

The documentation requirement is annulled if the class or module has a "#:nodoc:" comment next to it. Likewise, "#:nodoc: all" does the same for all its children.

Example:

# bad
class Person
  # ...
end
 
module Math
end
 
# good
# Description/Explanation of Person class
class Person
  # ...
end
 
# allowed
  # Class without body
  class Person
  end
 
  # Namespace - A namespace can be a class or a module
  # Containing a class
  module Namespace
    # Description/Explanation of Person class
    class Person
      # ...
    end
  end
 
  # Containing constant visibility declaration
  module Namespace
    class Private
    end
 
    private_constant :Private
  end
 
  # Containing constant definition
  module Namespace
    Public = Class.new
  end
 
  # Macro calls
  module Namespace
    extend Foo
  end

Example: AllowedConstants: ['ClassMethods']

# good
 module A
   module ClassMethods
     # ...
   end
  end

Use symbols as procs when possible.

If you prefer a style that allows block for method with arguments, please set true to AllowMethodsWithArguments. define_method? methods are allowed by default. These are customizable with AllowedMethods option.

Safety:

This cop is unsafe because there is a difference that a Proc generated from Symbol#to_proc behaves as a lambda, while a Proc generated from a block does not. For example, a lambda will raise an ArgumentError if the number of arguments is wrong, but a non-lambda Proc will not.

For example:

class Foo
  def bar
    :bar
  end
end
 
def call(options = {}, &block)
  block.call(Foo.new, options)
end
 
call { |x| x.bar }
#=> :bar
call(&:bar)
# ArgumentError: wrong number of arguments (given 1, expected 0)

Example:

# bad
something.map { |s| s.upcase }
something.map { _1.upcase }
 
# good
something.map(&:upcase)

Example: AllowMethodsWithArguments: false (default)

# bad
something.do_something(foo) { |o| o.bar }
 
# good
something.do_something(foo, &:bar)

Example: AllowMethodsWithArguments: true

# good
something.do_something(foo) { |o| o.bar }

Example: AllowComments: false (default)

# bad
something.do_something do |s| # some comment
  # some comment
  s.upcase # some comment
  # some comment
end

Example: AllowComments: true

# good  - if there are comment in either position
something.do_something do |s| # some comment
  # some comment
  s.upcase # some comment
  # some comment
end

Example: AllowedMethods: [define_method] (default)

# good
define_method(:foo) { |foo| foo.bar }

Example: AllowedPatterns: [] (default)

# bad
something.map { |s| s.upcase }

Example: AllowedPatterns: ['map'] (default)

# good
something.map { |s| s.upcase }

Checks that block braces have or don't have a space before the opening brace depending on configuration.

Example: EnforcedStyle: space (default)

# bad
foo.map{ |a|
  a.bar.to_s
}
 
# good
foo.map { |a|
  a.bar.to_s
}

Example: EnforcedStyle: no_space

# bad
foo.map { |a|
  a.bar.to_s
}
 
# good
foo.map{ |a|
  a.bar.to_s
}

Example: EnforcedStyleForEmptyBraces: space (default)

# bad
7.times{}
 
# good
7.times {}

Example: EnforcedStyleForEmptyBraces: no_space

# bad
7.times {}
 
# good
7.times{}

Checks for indentation that doesn't use the specified number of spaces.

See also the IndentationConsistency cop which is the companion to this one.

Example:

# bad
class A
 def test
  puts 'hello'
 end
end
 
# good
class A
  def test
    puts 'hello'
  end
end

Example: AllowedPatterns: ['^\s*module']

# bad
module A
class B
  def test
  puts 'hello'
  end
end
end
 
# good
module A
class B
  def test
    puts 'hello'
  end
end
end

Checks that block braces have or don't have surrounding space inside them on configuration. For blocks taking parameters, it checks that the left brace has or doesn't have trailing space depending on configuration.

Example: EnforcedStyle: space (default)

# The `space` style enforces that block braces have
# surrounding space.
 
# bad
some_array.each {puts e}
 
# good
some_array.each { puts e }

Example: EnforcedStyle: no_space

# The `no_space` style enforces that block braces don't
# have surrounding space.
 
# bad
some_array.each { puts e }
 
# good
some_array.each {puts e}

Example: EnforcedStyleForEmptyBraces: no_space (default)

# The `no_space` EnforcedStyleForEmptyBraces style enforces that
# block braces don't have a space in between when empty.
 
# bad
some_array.each {   }
some_array.each {  }
some_array.each { }
 
# good
some_array.each {}

Example: EnforcedStyleForEmptyBraces: space

# The `space` EnforcedStyleForEmptyBraces style enforces that
# block braces have at least a space in between when empty.
 
# bad
some_array.each {}
 
# good
some_array.each { }
some_array.each {  }
some_array.each {   }

Example: SpaceBeforeBlockParameters: true (default)

# The SpaceBeforeBlockParameters style set to `true` enforces that
# there is a space between `{` and `|`. Overrides `EnforcedStyle`
# if there is a conflict.
 
# bad
[1, 2, 3].each {|n| n * 2 }
 
# good
[1, 2, 3].each { |n| n * 2 }

Example: SpaceBeforeBlockParameters: false

# The SpaceBeforeBlockParameters style set to `false` enforces that
# there is no space between `{` and `|`. Overrides `EnforcedStyle`
# if there is a conflict.
 
# bad
[1, 2, 3].each { |n| n * 2 }
 
# good
[1, 2, 3].each {|n| n * 2 }

Checks hash literal syntax.

It can enforce either the use of the class hash rocket syntax or the use of the newer Ruby 1.9 syntax (when applicable).

A separate offense is registered for each problematic pair.

The supported styles are:

• ruby19 - forces use of the 1.9 syntax (e.g. {a: 1}) when hashes have all symbols for keys
• hash_rockets - forces use of hash rockets for all hashes
• nomixedkeys - simply checks for hashes with mixed syntaxes
• ruby19nomixed_keys - forces use of ruby 1.9 syntax and forbids mixed syntax hashes

This cop has EnforcedShorthandSyntax option. It can enforce either the use of the explicit hash value syntax or the use of Ruby 3.1's hash value shorthand syntax.

The supported styles are:

• always - forces use of the 3.1 syntax (e.g. {foo:})
• never - forces use of explicit hash literal value
• either - accepts both shorthand and explicit use of hash literal value
• consistent - forces use of the 3.1 syntax only if all values can be omitted in the hash

Example: EnforcedStyle: ruby19 (default)

# bad
{:a => 2}
{b: 1, :c => 2}
 
# good
{a: 2, b: 1}
{:c => 2, 'd' => 2} # acceptable since 'd' isn't a symbol
{d: 1, 'e' => 2} # technically not forbidden

Example: EnforcedStyle: hash_rockets

# bad
{a: 1, b: 2}
{c: 1, 'd' => 5}
 
# good
{:a => 1, :b => 2}

Example: EnforcedStyle: nomixedkeys

# bad
{:a => 1, b: 2}
{c: 1, 'd' => 2}
 
# good
{:a => 1, :b => 2}
{c: 1, d: 2}

Example: EnforcedStyle: ruby19nomixed_keys

# bad
{:a => 1, :b => 2}
{c: 2, 'd' => 3} # should just use hash rockets
 
# good
{a: 1, b: 2}
{:c => 3, 'd' => 4}

Example: EnforcedShorthandSyntax: always (default)

# bad
{foo: foo, bar: bar}
 
# good
{foo:, bar:}

Example: EnforcedShorthandSyntax: never

# bad
{foo:, bar:}
 
# good
{foo: foo, bar: bar}

Example: EnforcedShorthandSyntax: either

# good
{foo: foo, bar: bar}
 
# good
{foo: foo, bar:}
 
# good
{foo:, bar:}

Example: EnforcedShorthandSyntax: consistent

# bad - `foo` and `bar` values can be omitted
{foo: foo, bar: bar}
 
# bad - `bar` value can be omitted
{foo:, bar: bar}
 
# bad - mixed syntaxes
{foo:, bar: baz}
 
# good
{foo:, bar:}
 
# good - can't omit `baz`
{foo: foo, bar: baz}

Checks if uses of quotes match the configured preference.

Example: EnforcedStyle: single_quotes (default)

# bad
"No special symbols"
"No string interpolation"
"Just text"
 
# good
'No special symbols'
'No string interpolation'
'Just text'
"Wait! What's #{this}!"

Example: EnforcedStyle: double_quotes

# bad
'Just some text'
'No special chars or interpolation'
 
# good
"Just some text"
"No special chars or interpolation"
"Every string in #{project} uses double_quotes"

Checks for indentation that doesn't use the specified number of spaces.

See also the IndentationConsistency cop which is the companion to this one.

Example:

# bad
class A
 def test
  puts 'hello'
 end
end
 
# good
class A
  def test
    puts 'hello'
  end
end

Example: AllowedPatterns: ['^\s*module']

# bad
module A
class B
  def test
  puts 'hello'
  end
end
end
 
# good
module A
class B
  def test
    puts 'hello'
  end
end
end

Helps you transition from mutable string literals to frozen string literals. It will add the # frozen_string_literal: true magic comment to the top of files to enable frozen string literals. Frozen string literals may be default in future Ruby. The comment will be added below a shebang and encoding comment. The frozen string literal comment is only valid in Ruby 2.3+.

Note that the cop will accept files where the comment exists but is set to false instead of true.

To require a blank line after this comment, please see Layout/EmptyLineAfterMagicComment cop.

Safety:

This cop's autocorrection is unsafe since any strings mutations will change from being accepted to raising FrozenError, as all strings will become frozen by default, and will need to be manually refactored.

Example: EnforcedStyle: always (default)

# The `always` style will always add the frozen string literal comment
# to a file, regardless of the Ruby version or if `freeze` or `<<` are
# called on a string literal.
# bad
module Bar
  # ...
end
 
# good
# frozen_string_literal: true
 
module Bar
  # ...
end
 
# good
# frozen_string_literal: false
 
module Bar
  # ...
end

Example: EnforcedStyle: never

# The `never` will enforce that the frozen string literal comment does
# not exist in a file.
# bad
# frozen_string_literal: true
 
module Baz
  # ...
end
 
# good
module Baz
  # ...
end

Example: EnforcedStyle: always_true

# The `always_true` style enforces that the frozen string literal
# comment is set to `true`. This is a stricter option than `always`
# and forces projects to use frozen string literals.
# bad
# frozen_string_literal: false
 
module Baz
  # ...
end
 
# bad
module Baz
  # ...
end
 
# good
# frozen_string_literal: true
 
module Bar
  # ...
end

Checks for indentation that doesn't use the specified number of spaces.

See also the IndentationConsistency cop which is the companion to this one.

Example:

# bad
class A
 def test
  puts 'hello'
 end
end
 
# good
class A
  def test
    puts 'hello'
  end
end

Example: AllowedPatterns: ['^\s*module']

# bad
module A
class B
  def test
  puts 'hello'
  end
end
end
 
# good
module A
class B
  def test
    puts 'hello'
  end
end
end

Checks if uses of quotes match the configured preference.

Example: EnforcedStyle: single_quotes (default)

# bad
"No special symbols"
"No string interpolation"
"Just text"
 
# good
'No special symbols'
'No string interpolation'
'Just text'
"Wait! What's #{this}!"

Example: EnforcedStyle: double_quotes

# bad
'Just some text'
'No special chars or interpolation'
 
# good
"Just some text"
"No special chars or interpolation"
"Every string in #{project} uses double_quotes"