Cognitive Complexity

Cognitive Complexity is a measure of how difficult a unit of code is to intuitively understand. Unlike Cyclomatic Complexity, which determines how difficult your code will be to test, Cognitive Complexity tells you how difficult your code will be to read and comprehend.

A method's cognitive complexity is based on a few simple rules:

• Code is not considered more complex when it uses shorthand that the language provides for collapsing multiple statements into one
• Code is considered more complex for each "break in the linear flow of the code"
• Code is considered more complex when "flow breaking structures are nested"

Further reading

• Cognitive Complexity docs
• Cognitive Complexity: A new way of measuring understandability

Checks that the cyclomatic complexity of methods is not higher than the configured maximum. The cyclomatic complexity is the number of linearly independent paths through a method. The algorithm counts decision points and adds one.

An if statement (or unless or ?:) increases the complexity by one. An else branch does not, since it doesn't add a decision point. The && operator (or keyword and) can be converted to a nested if statement, and ||/or is shorthand for a sequence of ifs, so they also add one. Loops can be said to have an exit condition, so they add one. Blocks that are calls to builtin iteration methods (e.g. `ary.map{...}) also add one, others are ignored.

def each_child_node(*types)               # count begins: 1
  unless block_given?                     # unless: +1
    return to_enum(__method__, *types)

  children.each do |child|                # each{}: +1
    next unless child.is_a?(Node)         # unless: +1

    yield child if types.empty? ||        # if: +1, ||: +1
                   types.include?(child.type)
  end

  self
end                                       # total: 6

Tries to produce a complexity score that's a measure of the complexity the reader experiences when looking at a method. For that reason it considers when nodes as something that doesn't add as much complexity as an if or a &&. Except if it's one of those special case/when constructs where there's no expression after case. Then the cop treats it as an if/elsif/elsif... and lets all the when nodes count. In contrast to the CyclomaticComplexity cop, this cop considers else nodes as adding complexity.

Example:

def my_method                   # 1
  if cond                       # 1
    case var                    # 2 (0.8 + 4 * 0.2, rounded)
    when 1 then func_one
    when 2 then func_two
    when 3 then func_three
    when 4..10 then func_other
    end
  else                          # 1
    do_something until a && b   # 2
  end                           # ===
end                             # 7 complexity points

Checks if the length of a method exceeds some maximum value. Comment lines can optionally be allowed. The maximum allowed length is configurable.

You can set constructs you want to fold with CountAsOne. Available are: 'array', 'hash', 'heredoc', and 'method_call'. Each construct will be counted as one line regardless of its actual size.

NOTE: The ExcludedMethods and IgnoredMethods configuration is deprecated and only kept for backwards compatibility. Please use AllowedMethods and AllowedPatterns instead. By default, there are no methods to allowed.

Example: CountAsOne: ['array', 'heredoc', 'method_call']

def m
  array = [       # +1
    1,
    2
  ]

  hash = {        # +3
    key: 'value'
  }

  <<~HEREDOC      # +1
    Heredoc
    content.
  HEREDOC

  foo(            # +1
    1,
    2
  )
end               # 6 points

Cognitive Complexity

Cognitive Complexity is a measure of how difficult a unit of code is to intuitively understand. Unlike Cyclomatic Complexity, which determines how difficult your code will be to test, Cognitive Complexity tells you how difficult your code will be to read and comprehend.

A method's cognitive complexity is based on a few simple rules:

• Code is not considered more complex when it uses shorthand that the language provides for collapsing multiple statements into one
• Code is considered more complex for each "break in the linear flow of the code"
• Code is considered more complex when "flow breaking structures are nested"

Further reading

• Cognitive Complexity docs
• Cognitive Complexity: A new way of measuring understandability

Checks the length of lines in the source code. The maximum length is configurable. The tab size is configured in the IndentationWidth of the Layout/IndentationStyle cop. It also ignores a shebang line by default.

This cop has some autocorrection capabilities. It can programmatically shorten certain long lines by inserting line breaks into expressions that can be safely split across lines. These include arrays, hashes, and method calls with argument lists.

If autocorrection is enabled, the following Layout cops are recommended to further format the broken lines. (Many of these are enabled by default.)

• ArgumentAlignment
• ArrayAlignment
• BlockAlignment
• BlockDelimiters
• BlockEndNewline
• ClosingParenthesisIndentation
• FirstArgumentIndentation
• FirstArrayElementIndentation
• FirstHashElementIndentation
• FirstParameterIndentation
• HashAlignment
• IndentationWidth
• MultilineArrayLineBreaks
• MultilineBlockLayout
• MultilineHashBraceLayout
• MultilineHashKeyLineBreaks
• MultilineMethodArgumentLineBreaks
• MultilineMethodParameterLineBreaks
• ParameterAlignment

Together, these cops will pretty print hashes, arrays, method calls, etc. For example, let's say the max columns is 25:

Example:

# bad
{foo: "0000000000", bar: "0000000000", baz: "0000000000"}

# good
{foo: "0000000000",
bar: "0000000000", baz: "0000000000"}

# good (with recommended cops enabled)
{
  foo: "0000000000",
  bar: "0000000000",
  baz: "0000000000",
}

Cognitive Complexity

Cognitive Complexity is a measure of how difficult a unit of code is to intuitively understand. Unlike Cyclomatic Complexity, which determines how difficult your code will be to test, Cognitive Complexity tells you how difficult your code will be to read and comprehend.

A method's cognitive complexity is based on a few simple rules:

• Code is not considered more complex when it uses shorthand that the language provides for collapsing multiple statements into one
• Code is considered more complex for each "break in the linear flow of the code"
• Code is considered more complex when "flow breaking structures are nested"

Further reading

• Cognitive Complexity docs
• Cognitive Complexity: A new way of measuring understandability

Checks the length of lines in the source code. The maximum length is configurable. The tab size is configured in the IndentationWidth of the Layout/IndentationStyle cop. It also ignores a shebang line by default.

This cop has some autocorrection capabilities. It can programmatically shorten certain long lines by inserting line breaks into expressions that can be safely split across lines. These include arrays, hashes, and method calls with argument lists.

If autocorrection is enabled, the following Layout cops are recommended to further format the broken lines. (Many of these are enabled by default.)

• ArgumentAlignment
• ArrayAlignment
• BlockAlignment
• BlockDelimiters
• BlockEndNewline
• ClosingParenthesisIndentation
• FirstArgumentIndentation
• FirstArrayElementIndentation
• FirstHashElementIndentation
• FirstParameterIndentation
• HashAlignment
• IndentationWidth
• MultilineArrayLineBreaks
• MultilineBlockLayout
• MultilineHashBraceLayout
• MultilineHashKeyLineBreaks
• MultilineMethodArgumentLineBreaks
• MultilineMethodParameterLineBreaks
• ParameterAlignment

Together, these cops will pretty print hashes, arrays, method calls, etc. For example, let's say the max columns is 25:

Example:

# bad
{foo: "0000000000", bar: "0000000000", baz: "0000000000"}

# good
{foo: "0000000000",
bar: "0000000000", baz: "0000000000"}

# good (with recommended cops enabled)
{
  foo: "0000000000",
  bar: "0000000000",
  baz: "0000000000",
}

Duplicated Code

Duplicated code can lead to software that is hard to understand and difficult to change. The Don't Repeat Yourself (DRY) principle states:

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

When you violate DRY, bugs and maintenance problems are sure to follow. Duplicated code has a tendency to both continue to replicate and also to diverge (leaving bugs as two similar implementations differ in subtle ways).

Tuning

This issue has a mass of 25.

We set useful threshold defaults for the languages we support but you may want to adjust these settings based on your project guidelines.

The threshold configuration represents the minimum mass a code block must have to be analyzed for duplication. The lower the threshold, the more fine-grained the comparison.

If the engine is too easily reporting duplication, try raising the threshold. If you suspect that the engine isn't catching enough duplication, try lowering the threshold. The best setting tends to differ from language to language.

See codeclimate-duplication's documentation for more information about tuning the mass threshold in your .codeclimate.yml.

Refactorings

• Extract Method
• Extract Class
• Form Template Method
• Introduce Null Object
• Pull Up Method
• Pull Up Field
• Substitute Algorithm

Further Reading

• Don't Repeat Yourself on the C2 Wiki
• Duplicated Code on SourceMaking
• Refactoring: Improving the Design of Existing Code by Martin Fowler. Duplicated Code, p76

Duplicated Code

Duplicated code can lead to software that is hard to understand and difficult to change. The Don't Repeat Yourself (DRY) principle states:

Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

When you violate DRY, bugs and maintenance problems are sure to follow. Duplicated code has a tendency to both continue to replicate and also to diverge (leaving bugs as two similar implementations differ in subtle ways).

Tuning

This issue has a mass of 25.

We set useful threshold defaults for the languages we support but you may want to adjust these settings based on your project guidelines.

The threshold configuration represents the minimum mass a code block must have to be analyzed for duplication. The lower the threshold, the more fine-grained the comparison.

If the engine is too easily reporting duplication, try raising the threshold. If you suspect that the engine isn't catching enough duplication, try lowering the threshold. The best setting tends to differ from language to language.

See codeclimate-duplication's documentation for more information about tuning the mass threshold in your .codeclimate.yml.

Refactorings

• Extract Method
• Extract Class
• Form Template Method
• Introduce Null Object
• Pull Up Method
• Pull Up Field
• Substitute Algorithm

Further Reading

• Don't Repeat Yourself on the C2 Wiki
• Duplicated Code on SourceMaking
• Refactoring: Improving the Design of Existing Code by Martin Fowler. Duplicated Code, p76

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

Check that the keys, separators, and values of a multi-line hash literal are aligned according to configuration. The configuration options are:

• key (left align keys, one space before hash rockets and values)
• separator (align hash rockets and colons, right align keys)
• table (left align keys, hash rockets, and values)

The treatment of hashes passed as the last argument to a method call can also be configured. The options are:

• always_inspect
• always_ignore
• ignore_implicit (without curly braces)

Alternatively you can specify multiple allowed styles. That's done by passing a list of styles to EnforcedStyles.

Example: EnforcedHashRocketStyle: key (default)

# bad
{
  :foo => bar,
   :ba => baz
}
{
  :foo => bar,
  :ba  => baz
}

# good
{
  :foo => bar,
  :ba => baz
}

Example: EnforcedHashRocketStyle: separator

# bad
{
  :foo => bar,
  :ba => baz
}
{
  :foo => bar,
  :ba  => baz
}

# good
{
  :foo => bar,
   :ba => baz
}

Example: EnforcedHashRocketStyle: table

# bad
{
  :foo => bar,
   :ba => baz
}

# good
{
  :foo => bar,
  :ba  => baz
}

Example: EnforcedColonStyle: key (default)

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

# good
{
  foo: bar,
  ba: baz
}

Example: EnforcedColonStyle: separator

# bad
{
  foo: bar,
  ba: baz
}

# good
{
  foo: bar,
   ba: baz
}

Example: EnforcedColonStyle: table

# bad
{
  foo: bar,
  ba: baz
}

# good
{
  foo: bar,
  ba:  baz
}

Example: EnforcedLastArgumentHashStyle: always_inspect (default)

# Inspect both implicit and explicit hashes.

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

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

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

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

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

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

Example: EnforcedLastArgumentHashStyle: always_ignore

# Ignore both implicit and explicit hashes.

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

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

Example: EnforcedLastArgumentHashStyle: ignore_implicit

# Ignore only implicit hashes.

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

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

Example: EnforcedLastArgumentHashStyle: ignore_explicit

# Ignore only explicit hashes.

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

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

Checks for redundant escapes inside Regexp literals.

Example:

# bad
%r{foo\/bar}

# good
%r{foo/bar}

# good
/foo\/bar/

# good
%r/foo\/bar/

# good
%r!foo\!bar!

# bad
/a\-b/

# good
/a-b/

# bad
/[\+\-]\d/

# good
/[+\-]\d/

Checks for redundant escapes inside Regexp literals.

Example:

# bad
%r{foo\/bar}

# good
%r{foo/bar}

# good
/foo\/bar/

# good
%r/foo\/bar/

# good
%r!foo\!bar!

# bad
/a\-b/

# good
/a-b/

# bad
/[\+\-]\d/

# good
/[+\-]\d/

Checks that required_ruby_version in a gemspec file is set to a valid value (non-blank) and matches TargetRubyVersion as set in RuboCop's configuration for the gem.

This ensures that RuboCop is using the same Ruby version as the gem.

Example:

# When `TargetRubyVersion` of .rubocop.yml is `2.5`.

# bad
Gem::Specification.new do |spec|
  # no `required_ruby_version` specified
end

# bad
Gem::Specification.new do |spec|
  spec.required_ruby_version = '>= 2.4.0'
end

# bad
Gem::Specification.new do |spec|
  spec.required_ruby_version = '>= 2.6.0'
end

# bad
Gem::Specification.new do |spec|
  spec.required_ruby_version = ''
end

# good
Gem::Specification.new do |spec|
  spec.required_ruby_version = '>= 2.5.0'
end

# good
Gem::Specification.new do |spec|
  spec.required_ruby_version = '>= 2.5'
end

# accepted but not recommended
Gem::Specification.new do |spec|
  spec.required_ruby_version = ['>= 2.5.0', '< 2.7.0']
end

# accepted but not recommended, since
# Ruby does not really follow semantic versioning
Gem::Specification.new do |spec|
  spec.required_ruby_version = '~> 2.5'
end

Check that the keys, separators, and values of a multi-line hash literal are aligned according to configuration. The configuration options are:

• key (left align keys, one space before hash rockets and values)
• separator (align hash rockets and colons, right align keys)
• table (left align keys, hash rockets, and values)

The treatment of hashes passed as the last argument to a method call can also be configured. The options are:

• always_inspect
• always_ignore
• ignore_implicit (without curly braces)

Alternatively you can specify multiple allowed styles. That's done by passing a list of styles to EnforcedStyles.

Example: EnforcedHashRocketStyle: key (default)

# bad
{
  :foo => bar,
   :ba => baz
}
{
  :foo => bar,
  :ba  => baz
}

# good
{
  :foo => bar,
  :ba => baz
}

Example: EnforcedHashRocketStyle: separator

# bad
{
  :foo => bar,
  :ba => baz
}
{
  :foo => bar,
  :ba  => baz
}

# good
{
  :foo => bar,
   :ba => baz
}

Example: EnforcedHashRocketStyle: table

# bad
{
  :foo => bar,
   :ba => baz
}

# good
{
  :foo => bar,
  :ba  => baz
}

Example: EnforcedColonStyle: key (default)

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

# good
{
  foo: bar,
  ba: baz
}

Example: EnforcedColonStyle: separator

# bad
{
  foo: bar,
  ba: baz
}

# good
{
  foo: bar,
   ba: baz
}

Example: EnforcedColonStyle: table

# bad
{
  foo: bar,
  ba: baz
}

# good
{
  foo: bar,
  ba:  baz
}

Example: EnforcedLastArgumentHashStyle: always_inspect (default)

# Inspect both implicit and explicit hashes.

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

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

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

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

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

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

Example: EnforcedLastArgumentHashStyle: always_ignore

# Ignore both implicit and explicit hashes.

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

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

Example: EnforcedLastArgumentHashStyle: ignore_implicit

# Ignore only implicit hashes.

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

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

Example: EnforcedLastArgumentHashStyle: ignore_explicit

# Ignore only explicit hashes.

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

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

Makes sure that Ruby source files have snake_case names. Ruby scripts (i.e. source files with a shebang in the first line) are ignored.

The cop also ignores .gemspec files, because Bundler recommends using dashes to separate namespaces in nested gems (i.e. bundler-console becomes Bundler::Console). As such, the gemspec is supposed to be named bundler-console.gemspec.

When ExpectMatchingDefinition (default: false) is true, the cop requires each file to have a class, module or Struct defined in it that matches the filename. This can be further configured using CheckDefinitionPathHierarchy (default: true) to determine whether the path should match the namespace of the above definition.

When IgnoreExecutableScripts (default: true) is true, files that start with a shebang line are not considered by the cop.

When Regex is set, the cop will flag any filename that does not match the regular expression.

Example:

# bad
lib/layoutManager.rb

anything/usingCamelCase

# good
lib/layout_manager.rb

anything/using_snake_case.rake

Checks the indentation of the method name part in method calls that span more than one line.

Example: EnforcedStyle: aligned (default)

# bad
while myvariable
.b
  # do something
end

# good
while myvariable
      .b
  # do something
end

# good
Thing.a
     .b
     .c

Example: EnforcedStyle: indented

# good
while myvariable
  .b

  # do something
end

Example: EnforcedStyle: indentedrelativeto_receiver

# good
while myvariable
        .a
        .b

  # do something
end

# good
myvariable = Thing
               .a
               .b
               .c

Checks for redundant escapes inside Regexp literals.

Example:

# bad
%r{foo\/bar}

# good
%r{foo/bar}

# good
/foo\/bar/

# good
%r/foo\/bar/

# good
%r!foo\!bar!

# bad
/a\-b/

# good
/a-b/

# bad
/[\+\-]\d/

# good
/[+\-]\d/

Checks the indentation of the method name part in method calls that span more than one line.

Example: EnforcedStyle: aligned (default)

# bad
while myvariable
.b
  # do something
end

# good
while myvariable
      .b
  # do something
end

# good
Thing.a
     .b
     .c

Example: EnforcedStyle: indented

# good
while myvariable
  .b

  # do something
end

Example: EnforcedStyle: indentedrelativeto_receiver

# good
while myvariable
        .a
        .b

  # do something
end

# good
myvariable = Thing
               .a
               .b
               .c