Style

Access modifiers should be declared to apply to a group of methods or inline before each method, depending on configuration. EnforcedStyle config covers only method definitions. Applications of visibility methods to symbols can be controlled using AllowModifiersOnSymbols config. Also, the visibility of attr* methods can be controlled using AllowModifiersOnAttrs config.

In Ruby 3.0, attr* methods now return an array of defined method names as symbols. So we can write the modifier and attr* in inline style. AllowModifiersOnAttrs config allows attr* methods to be written in inline style without modifying applications that have been maintained for a long time in group style. Furthermore, developers who are not very familiar with Ruby may know that the modifier applies to def, but they may not know that it also applies to attr* methods. It would be easier to understand if we could write attr* methods in inline style.

Checks for grouping of accessors in class and module bodies. By default it enforces accessors to be placed in grouped declarations, but it can be configured to enforce separating them in multiple declarations.

Enforces the use of either #alias or #alias_method depending on configuration. It also flags uses of alias :symbol rather than alias bareword.

However, it will always enforce method_alias when used alias in an instance method definition and in a singleton method definition. If used in a block, always enforce alias_method unless it is an instance_eval block.

Looks for endless methods inside operations of lower precedence (and, or, and modifier forms of if, unless, while, until) that are ambiguous due to lack of parentheses. This may lead to unexpected behavior as the code may appear to use these keywords as part of the method but in fact they modify the method definition itself.

In these cases, using a normal method definition is more clear.

Checks for uses of and and or, and suggests using && and || instead. It can be configured to check only in conditions or in all contexts.

In Ruby 2.7, arguments forwarding has been added.

This cop identifies places where do_something(*args, &block) can be replaced by do_something(…​).

In Ruby 3.1, anonymous block forwarding has been added.

This cop identifies places where do_something(&block) can be replaced by do_something(&); if desired, this functionality can be disabled by setting UseAnonymousForwarding: false.

In Ruby 3.2, anonymous args/kwargs forwarding has been added.

This cop also identifies places where use_args(args)/use_kwargs(kwargs) can be replaced by use_args()/use_kwargs(); if desired, this functionality can be disabled by setting UseAnonymousForwarding: false.

And this cop has RedundantRestArgumentNames, RedundantKeywordRestArgumentNames, and RedundantBlockArgumentNames options. This configuration is a list of redundant names that are sufficient for anonymizing meaningless naming.

Meaningless names that are commonly used can be anonymized by default: e.g., args, *options, &block, and so on.

Names not on this list are likely to be meaningful and are allowed by default.

This cop handles not only method forwarding but also forwarding to super.

Enforces the use of Array() instead of explicit Array check or [*var].

The cop is disabled by default due to safety concerns.

Identifies usages of arr[0] and arr[-1] and suggests to change them to use arr.first and arr.last instead.

The cop is disabled by default due to safety concerns.

In Ruby 3.1, Array#intersect? has been added.

This cop identifies places where (array1 & array2).any? can be replaced by array1.intersect?(array2).

The array1.intersect?(array2) method is faster than (array1 & array2).any? and is more readable.

In cases like the following, compatibility is not ensured, so it will not be detected when using block argument.

Checks for uses of "*" as a substitute for join.

Not all cases can reliably checked, due to Ruby’s dynamic types, so we consider only cases when the first argument is an array literal or the second is a string literal.

Checks for non-ascii (non-English) characters in comments. You could set an array of allowed non-ascii chars in AllowedChars attribute (copyright notice "©" by default).

Checks for uses of Module#attr.

Checks for cases when you could use a block accepting version of a method that does automatic resource cleanup.

Checks if usage of %() or %Q() matches configuration.

Checks for BEGIN blocks.

Checks for places where attr_reader and attr_writer for the same method can be combined into single attr_accessor.

Prefer bitwise predicate methods over direct comparison operations.

Looks for uses of block comments (=begin…​=end).

Check for uses of braces or do/end around single line or multi-line blocks.

Methods that can be either procedural or functional and cannot be categorised from their usage alone is ignored. lambda, proc, and it are their defaults. Additional methods can be added to the AllowedMethods.

If AllowOnSelfClass option is enabled, the cop will ignore violations when the receiver of the case equality operator is self.class. Note intermediate variables are not accepted.

Identifies places where if-elsif constructions can be replaced with case-when.

Checks for uses of the character literal ?x. Starting with Ruby 1.9 character literals are essentially one-character strings, so this syntax is mostly redundant at this point.

? character literal can be used to express meta and control character. That’s a good use case of ? literal so it doesn’t count it as an offense.

Checks the style of children definitions at classes and modules. Basically there are two different styles:

The compact style is only forced for classes/modules with one child.

Enforces consistent use of Object#is_a? or Object#kind_of?.

Enforces the use of Object#instance_of? instead of class comparison for equality. ==, equal?, and eql? custom method definitions are allowed by default. These are customizable with AllowedMethods option.

Checks for uses of the class/module name instead of self, when defining class/module methods.

Enforces using def self.method_name or class << self to define class methods.

Checks for uses of class variables. Offenses are signaled only on assignment to class variables to reduce the number of offenses that would be reported.

You have to be careful when setting a value for a class variable; if a class has been inherited, changing the value of a class variable also affects the inheriting classes. This means that it’s almost always better to use a class instance variable instead.

Checks for places where custom logic on rejection nils from arrays and hashes can be replaced with {Array,Hash}#{compact,compact!}.

Enforces the use of consistent method names from the Enumerable module.

You can customize the mapping from undesired method to desired method.

e.g. to use detect over find:

Checks for methods invoked via the :: operator instead of the . operator (like FileUtils::rmdir instead of FileUtils.rmdir).

Checks for class methods that are defined using the :: operator instead of the . operator.

Checks for multiple defined? calls joined by && that can be combined into a single defined?.

When checking that a nested constant or chained method is defined, it is not necessary to check each ancestor or component of the chain.

Checks for places where multiple consecutive loops over the same data can be combined into a single loop. It is very likely that combining them will make the code more efficient and more concise.

Enforces using `` or %x around command literals.

Checks that comment annotation keywords are written according to guidelines.

Annotation keywords can be specified by overriding the cop’s Keywords configuration. Keywords are allowed to be single words or phrases.

Checks for comments put on the same line as some keywords. These keywords are: class, module, def, begin, end.

Note that some comments (:nodoc:, :yields:, rubocop:disable and rubocop:todo) and RBS::Inline annotation comments are allowed.

Autocorrection removes comments from end keyword and keeps comments for class, module, def and begin above the keyword.

Enforces the use of Comparable#clamp instead of comparison by minimum and maximum.

This cop supports autocorrection for if/elsif/else bad style only. Because ArgumentError occurs if the minimum and maximum of clamp arguments are reversed. When these are variables, it is not possible to determine which is the minimum and maximum:

Enforces the use of Array#push(item) instead of Array#concat([item]) to avoid redundant array literals.

Check for if and case statements where each branch is used for both the assignment and comparison of the same variable when using the return of the condition can be used instead.

Checks that constants defined in classes and modules have an explicit visibility declaration. By default, Ruby makes all class- and module constants public, which litters the public API of the class or module. Explicitly declaring a visibility makes intent more clear, and prevents outside actors from touching private state.

Check that a copyright notice was given in each source file.

The default regexp for an acceptable copyright notice can be found in config/default.yml. The default can be changed as follows:

This regex string is treated as an unanchored regex. For each file that RuboCop scans, a comment that matches this regex must be found or an offense is reported.

Checks for inheritance from Data.define to avoid creating the anonymous parent class.

Checks for consistent usage of the DateTime class over the Time class. This cop is disabled by default since these classes, although highly overlapping, have particularities that make them not replaceable in certain situations when dealing with multiple timezones and/or DST.

Checks for parentheses in the definition of a method, that does not take any arguments. Both instance and class/singleton methods are checked.

Check for chained dig calls that can be collapsed into a single dig.

Checks for places where the #_\_dir\_\_ method can replace more complex constructs to retrieve a canonicalized absolute path to the current file.

Prefer to use Dir.empty?('path/to/dir') when checking if a directory is empty.

Detects comments to enable/disable RuboCop. This is useful if want to make sure that every RuboCop error gets fixed and not quickly disabled with a comment.

Specific cops can be allowed with the AllowedCops configuration. Note that if this configuration is set, rubocop:disable all is still disallowed.

When using class_eval (or other eval) with string interpolation, add a comment block showing its appearance if interpolated (a practice used in Rails code).

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.

Checks for missing documentation comment for public methods. It can optionally be configured to also require documentation for non-public methods.

Detects double disable comments on one line. This is mostly to catch automatically generated comments that need to be regenerated.

Checks for uses of double negation (!!) to convert something to a boolean value.

When using EnforcedStyle: allowed_in_returns, allow double negation in contexts that use boolean as a return value. When using EnforcedStyle: forbidden, double negation should be forbidden always.

Checks for loops which iterate a constant number of times, using a Range literal and #each. This can be done more readably using Integer#times.

This check only applies if the block takes no parameters.

Looks for inject / reduce calls where the passed in object is returned at the end and so could be replaced by each_with_object without the need to return the object at the end.

However, we can’t replace with each_with_object if the accumulator parameter is assigned to within the block.

Checks for pipes for empty block parameters. Pipes for empty block parameters do not cause syntax errors, but they are redundant.

Checks for case statements with an empty condition.

Checks for empty else-clauses, possibly including comments and/or an explicit nil depending on the EnforcedStyle.

Checks for using empty heredoc to reduce redundancy.

Checks for parentheses for empty lambda parameters. Parentheses for empty lambda parameters do not cause syntax errors, but they are redundant.

Checks for the use of a method, the result of which would be a literal, like an empty array, hash, or string.

Checks for the formatting of empty method definitions. By default it enforces empty method definitions to go on a single line (compact style), but it can be configured to enforce the end to go on its own line (expanded style).

Checks ensures source files have no utf-8 encoding comments.

Checks for END blocks.

Checks for endless methods.

It can enforce either the use of endless methods definitions for single-lined method bodies, or disallow endless methods.

Other method definition types are not considered by this cop.

The supported styles are:

Checks for consistent usage of ENV['HOME']. If nil is used as the second argument of ENV.fetch, it is treated as a bad case like ENV[].

Ensures that eval methods (eval, instance_eval, class_eval and module_eval) are given filename and line number values (_\_FILE\__ and \__LINE\_\_). This data is used to ensure that any errors raised within the evaluated code will be given the correct identification in a backtrace.

The cop also checks that the line number given relative to _\_LINE\_\_ is correct.

This cop will autocorrect incorrect or missing filename and line number values. However, if eval is called without a binding argument, the cop will not attempt to automatically add a binding, or add filename and line values.

Checks for places where Integer#even? or Integer#odd? can be used.

Checks for exact regexp match inside Regexp literals.

Checks for use of the File.expand_path arguments. Likewise, it also checks for the Pathname.new argument.

Contrastive bad case and good case are alternately shown in the following examples.

Enforces the use of explicit block argument to avoid writing block literal that just passes its arguments to another block.

Enforces consistency when using exponential notation for numbers in the code (eg 1.2e4). Different styles are supported:

Suggests ENV.fetch for the replacement of ENV[]. ENV[] silently fails and returns nil when the environment variable is unset, which may cause unexpected behaviors when the developer forgets to set it. On the other hand, ENV.fetch raises KeyError or returns the explicitly specified default value.

Prefer to use File.empty?('path/to/file') when checking if a file is empty.

Use File::NULL instead of hardcoding the null device (/dev/null on Unix-like OSes, NUL or NUL: on Windows), so that code is platform independent. Only looks for full string matches, substrings within a longer string are not considered.

Favor File.(bin)read convenience methods.

Checks for usage of File.open in append mode with empty block.

Such a usage only creates a new file, but it doesn’t update timestamps for an existing file, which might have been the intention.

For example, for an existing file foo.txt:

If the intention was to update timestamps, FileUtils.touch('foo.txt') should be used instead.

Favor File.(bin)write convenience methods.

Checks for division with integers coerced to floats. It is recommended to either always use fdiv or coerce one side only. This cop also provides other options for code consistency.

Looks for uses of the for keyword or each method. The preferred alternative is set in the EnforcedStyle configuration parameter. An each call with a block on a single line is always allowed.

Enforces the use of a single string formatting utility. Valid options include Kernel#format, Kernel#sprintf, and String#%.

The detection of String#% cannot be implemented in a reliable manner for all cases, so only two scenarios are considered - if the first argument is a string literal and if the second argument is an array literal.

Autocorrection will be applied when using argument is a literal or known built-in conversion methods such as to_d, to_f, to_h, to_i, to_r, to_s, and to_sym on variables, provided that their return value is not an array. For example, when using to_s, '%s' % [1, 2, 3].to_s can be autocorrected without any incompatibility:

Use a consistent style for named format string tokens.

This cop’s allowed methods can be customized with AllowedMethods. By default, there are no allowed methods.

It is allowed to contain unannotated token if the number of them is less than or equals to MaxUnannotatedPlaceholdersAllowed.

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.

Enforces the use of $stdout/$stderr/$stdin instead of STDOUT/STDERR/STDIN. STDOUT/STDERR/STDIN are constants, and while you can actually reassign (possibly to redirect some stream) constants in Ruby, you’ll get an interpreter warning if you do so.

Looks for uses of global variables. It does not report offenses for built-in global variables. Built-in global variables are allowed by default. Additionally users can allow additional variables via the AllowedVariables option.

Note that backreferences like $1, $2, etc are not global variables.

Use a guard clause instead of wrapping the code inside a conditional expression

A condition with an elsif or else branch is allowed unless one of return, break, next, raise, or fail is used in the body of the conditional expression.

Checks for presence or absence of braces around hash literal as a last array item depending on configuration.

Checks the usage of pre-2.1 Hash[args] method of converting enumerables and sequences of values to hashes.

Correction code from splat argument (Hash[*ary]) is not simply determined. For example, Hash[*ary] can be replaced with ary.each_slice(2).to_h but it will be complicated. So, AllowSplatArgument option is true by default to allow splat argument for simple code.

Checks for uses of each_key and each_value Hash methods.

Checks for usages of Hash#reject, Hash#select, and Hash#filter methods that can be replaced with Hash#except method.

This cop should only be enabled on Ruby version 3.0 or higher. (Hash#except was added in Ruby 3.0.)

For safe detection, it is limited to commonly used string and symbol comparisons when used ==. And do not check Hash#delete_if and Hash#keep_if to change receiver object.

Checks for places where case-when represents a simple 1:1 mapping and can be replaced with a hash lookup.

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:

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:

Looks for uses of _.each_with_object({}) {…​}, \_.map {…​}.to_h, and Hash[\_.map {…​}] that are actually just transforming the keys of a hash, and tries to use a simpler & faster call to transform_keys instead. It should only be enabled on Ruby version 2.5 or newer. (transform_keys was added in Ruby 2.5.)

Looks for uses of _.each_with_object({}) {…​}, \_.map {…​}.to_h, and Hash[\_.map {…​}] that are actually just transforming the values of a hash, and tries to use a simpler & faster call to transform_values instead.

Checks for identical expressions at the beginning or end of each branch of a conditional expression. Such expressions should normally be placed outside the conditional expression - before or after it.

If the else branch of a conditional consists solely of an if node, it can be combined with the else to become an elsif. This helps to keep the nesting level from getting too deep.

Checks for if and unless statements that would fit on one line if written as modifier if/unless. The cop also checks for modifier if/unless lines that exceed the maximum line length.

The maximum line length is configured in the Layout/LineLength cop. The tab size is configured in the IndentationWidth of the Layout/IndentationStyle cop.

One-line pattern matching is always allowed. To ensure that there are few cases where the match variable is not used, and to prevent oversights. The variable x becomes undefined and raises NameError when the following example is changed to the modifier form:

Checks for if and unless statements used as modifiers of other if or unless statements.

Checks for redundant if with boolean literal branches. It checks only conditions to return boolean value (true or false) for safe detection. The conditions to be checked are comparison methods, predicate methods, and double negation (!!). nonzero? method is allowed by default. These are customizable with AllowedMethods option.

This cop targets only if`s with a single `elsif or else branch. The following code will be allowed, because it has two elsif branches:

Checks for uses of semicolon in if statements.

Checks for raise or fail statements which do not specify an explicit exception class. (This raises a RuntimeError. Some projects might prefer to use exception classes which more precisely identify the nature of the error.)

Checks for in; uses in case expressions.

Use Kernel#loop for infinite loops.

Checks for trailing inline comments.

Check for usages of not (not or !) called on a method when an inverse of that method can be used instead.

Methods that can be inverted by a not (not or !) should be defined in InverseMethods.

Methods that are inverted by inverting the return of the block that is passed to the method should be defined in InverseBlocks.

Checks for usages of unless which can be replaced by if with inverted condition. Code without unless is easier to read, but that is subjective, so this cop is disabled by default.

Methods that can be inverted should be defined in InverseMethods. Note that the relationship of inverse methods needs to be defined in both directions. For example,

will suggest both even? and odd? to be inverted, but only != (and not ==).

Checks for hardcoded IP addresses, which can make code brittle. IP addresses are likely to need to be changed when code is deployed to a different server or environment, which may break a deployment if forgotten. Prefer setting IP addresses in ENV or other configuration.

When passing an existing hash as keyword arguments, provide additional arguments directly rather than using merge.

Providing arguments directly is more performant than using merge, and also leads to shorter and simpler code.

Enforces that optional keyword parameters are placed at the end of the parameters list.

This improves readability, because when looking through the source, it is expected to find required parameters at the beginning of parameters list and optional parameters at the end.