Common Mistakes and Gotchas

Array.new(size, object) stores the same object in every slot, and Hash.new(object) returns the same object for every missing key without storing it. Both are fine for immutable values (Array.new(3, 0), Hash.new(0)), and both are a trap for anything you intend to mutate. The block forms run the block once per slot or once per missing key, so each gets a fresh object. A default argument that points at a mutable constant has the same problem on the method side.

Source: Array.new, Hash.new

The array case prints four copies of "a" because the three rows are one object (object_id reports a single id). The hash case is worse: shelves[:fiction] << "Emma" mutates the shared default array and stores nothing, so shelves stays empty while shelves[:history] now answers ["Emma"]. The block form assigns into the hash (hash[key] = []), which is what makes later lookups find the same array again. Hash.new(0) is safe because += assigns a new integer back with []= instead of mutating one. RuboCop’s Lint/SharedMutableDefault reports the Hash.new([]) line; it does not report Array.new(3, []), and Style/MutableConstant reports the unfrozen DEFAULT_TAGS, which is the real source of the third problem: a method that appends to its default argument mutates a constant, so tag_safely builds a new array instead.

Array#each walks by index. Deleting an element shifts the rest down, so the index then points past the next element and that element is never visited. A Hash refuses to grow while it is being iterated.

Source: Array#reject!, Hash#transform_values

In the first run Dracula is deleted, Persuasion slides into the index that was just visited, the loop moves on to Ulysses, and Persuasion is never tested: it is longer than five characters and should have been removed, but it survives. The result depends on the data, which is what makes the bug hard to see. reject returns a new array and reject! (or delete_if) removes safely in place. Adding a new key to a hash raises RuntimeError ("can’t add a new key into hash during iteration"); assigning to existing keys is allowed, and transform_values or to_h with a block is usually clearer. The same idea applies to Set and to any Enumerator built on the collection.

and, or and not have the lowest precedence of all operators, lower than assignment. They are control-flow operators, meant for do_this or raise, not for boolean arithmetic.

Source: Operator precedence

ok = available and overdue parses as (ok = available) and overdue, so ok is true although the combined condition is false; ok = (available and overdue) or ok = available && overdue is what was meant. In the same way status = lookup("missing") or puts "lookup failed" assigns nil first and then runs puts. That is the legitimate use of or, and it works because the or sees the already-assigned nil. not copies == 3 is not (copies == 3), but !copies == 3 is (!copies) == 3, which compares false with 3; both are false here by coincidence, so use !=. RuboCop’s Style/AndOr flags and/or only inside conditions by default, so it does not catch the assignment case above; the style guide’s advice is to never use them for values.

Only nil and false are false. 0, "", [] and {} are truthy, which surprises programmers from C, Python or JavaScript. Combine that with = where == was meant and the condition is always true.

Output of ruby -w -Ilib f04_assign_in_condition.rb:

Source: Control Expressions

if copies = 0 assigns 0 to copies and then tests the result, 0, which is truthy, so the branch runs and the variable is clobbered. Ruby prints found '= literal' in conditional, should be == when the right-hand side is a literal; Ruby 4.0.7 printed it twice for this line, and an assignment from a method call gets no warning at all. When the assignment is intended, as in the match example, wrap it in parentheses; RuboCop’s Lint/AssignmentInCondition accepts that form. Lint/LiteralAssignmentInCondition reports the literal case. To test for zero, write copies.zero? (RuboCop’s Style/NumericPredicate prefers it to copies == 0).

rescue Exception catches everything, including Interrupt (Ctrl-C), SystemExit (exit), NoMemoryError and SignalException, so a program can no longer be stopped from the keyboard. A bare rescue (or rescue => e) catches only StandardError and its descendants, which is almost always what you want. The opposite mistake is a handler for a class that the code never raises.

Output of ruby -w -Ilib f05_rescue.rb:

Source: Exception, Exceptions

The first handler swallows the Interrupt raised by long_job and the program carries on; Lint/RescueException reports it. Integer("x") raises ArgumentError, a StandardError, which the plain handler sees. The hierarchy lines show why: Interrupt, SystemExit, ScriptError (and with it NotImplementedError and LoadError) descend from Exception directly. The nested example raises ParseError inside a begin that rescues only StoreError, so it propagates to the outer handler; listing both classes in one rescue (or giving them a common parent) handles it. Note that NoMatchingPatternError is a StandardError, whereas the SyntaxError raised by eval or load is a ScriptError. More detail on retry, ensure and custom hierarchies is in Exceptions and Error Handling.

Abstract methods are often written as raise NotImplementedError. Because the class descends from ScriptError, the ordinary rescue does not catch it, and a missing method implementation can crash a worker that was written to log and carry on.

Output of ruby -w -Ilib f06_not_implemented.rb:

Source: NotImplementedError

The documentation describes NotImplementedError as the error for a feature that the platform does not provide, such as fork on some systems, and not for abstract methods. Two reasonable alternatives are to leave the method undefined (a caller then gets NoMethodError, a StandardError, and respond_to? answers false) or to raise a StandardError subclass such as the NoMethodError shown above. Subclassing NotImplementedError is fine if every caller rescues it explicitly. See Classes and Objects for abstract-base-class patterns.

A bare super (zsuper) passes the current values of the method’s own parameters, including keyword and block arguments, to the parent method. super() passes none, and super(args) passes exactly those.

Source: Methods, including super

WithImplicit forwards title and year: to Base, so year is 1900. WithEmpty calls super(), so Base falls back to its defaults and the title is "untitled"; RuboCop reports the parameter that is now unused (Lint/UnusedMethodArgument). The bare super in ReassignsFirst sees the reassigned local title, because it passes the current value of the variable, not the argument originally received: "EMMA". That is convenient, and a surprise to anyone who expected the original argument. Two failure modes follow. A bare super in a method that has since gained parameters that the parent does not accept raises ArgumentError; and an initialize that omits super entirely leaves the parent’s state uninitialized, which Lint/MissingSuper reports for classes with a superclass. The full lookup rules, including super inside define_method (where the implicit form is not allowed), are in Method Lookup and super.

inherited, included, extended, prepended, method_added and the other hooks are ordinary methods. Defining one on your class replaces the version inherited from an ancestor, so a hook that forgets super silently disables whatever the ancestor chain did. A second trap is class-level state: instance variables on a class are per class, not inherited.

Source: Class#inherited, Module#included

Plugin.registry lists CsvPlugin, but CsvPlugin.registry is empty: the hook runs with self set to Plugin, the class whose singleton method is called, so it fills the @registry variable of Plugin, and an instance variable of a class is not inherited by its subclasses: CsvPlugin has a variable of its own that was never filled. The Tracked version shows the repair: initialise per-subclass state in the hook and call super first so that any hook defined above Tracked, or in a module the class extends, keeps working. Lint/MissingSuper reports the first inherited definition. The included hook follows the same rule. The default implementations of these hooks do nothing, so super is harmless when no ancestor defines one and essential when one does. The hook catalogue is in Hooks, eval and DSLs.

Ruby lets you assign a constant again; it warns and the new value replaces the old. Constants are also not immutable: the name is fixed, the object is not, and freeze is shallow.

Output of ruby -w -Ilib f09_constants.rb:

Source: Assignment

The first two lines of output are the already initialized constant warning and the pointer to the previous definition; the value is 5 afterwards. Lint/ConstantReassignment reports the second assignment statically. A frozen NAMES rejects << with FrozenError, but TAGS shows the limit of freeze: the array is frozen and the strings inside it are not, so TAGS.first << "!" succeeds. With # frozen_string_literal: true string literals are frozen anyway (hence the +"a" to build mutable ones); %w[Emma Dracula].freeze is a frozen array of frozen strings, which is why NAMES needs no map(&:freeze). To change a frozen hash, build a new one with merge. Assigning a constant inside a method body is a SyntaxError ("dynamic constant assignment").

a ||= b means a || (a = b). It assigns when a is nil or false, which is a bug when false (or a deliberately stored nil) is a legitimate value. 0 and "" are truthy, so they are not replaced.

Source: Abbreviated assignment, Hash#fetch

config[:color] ||= true turns an explicit false into true, while retries stays 0. For options use fetch(key, default), which distinguishes a missing key from a stored false or nil, or key? as in the second block. Use nil? when only nil should be replaced. The last example repeats the mistake with a memoized flag: memo[:ready] ||= ... recomputes every time while the stored value is false, which also makes ||= unsuitable for memoizing a method that may return false or nil; use defined?(@x) or instance_variable_defined? for that.

puts writes to_s and flattens arrays, so nil, [], "" and [nil] all look nearly the same. p writes inspect, returns its argument (so it can be dropped into the middle of an expression) and pp does the same with line wrapping.

Output of ruby -w -Ilib f11_puts_p.rb:

Source: Kernel#puts, Kernel#p

puts nil prints an empty line, puts [] prints nothing at all (the second blank line comes from puts [nil], and p nil is the only line that says nil), puts [1, [2, 3]] prints one element per line, and puts returns nil while p returns its argument. The Shelf::Isbn value prints its digits through to_s with puts and its #<data ...> form with p. Use p when debugging, and Logger or an explicit $stderr.puts for diagnostics in programs; Logger is a bundled gem in 4.0 and needs a Gemfile entry under Bundler.

Float is binary floating point, so most decimal fractions are approximations. Integer division truncates toward negative infinity, and dividing a float by zero gives Infinity rather than an error.

Source: Float, Rational, BigDecimal

19.99 * 100 is 1998.9999999999998, and to_i truncates it to 1998. Keep money as integer minor units (cents) and format at the edge, or use BigDecimal("19.99") (a string literal, never a float) or Rational("19.99"). BigDecimal is a bundled gem since Ruby 3.4, so under Bundler it needs a Gemfile entry. Compare floats with a tolerance (Lint/FloatComparison reports ==), or Float#round, not with ==. Integer division 10 / 4 is 2; use fdiv or a float operand for 2.5; -7 / 2 is -4 (floor), whereas remainder follows the sign of the dividend. The numeric tower is described in Numbers.

Time.now follows the system clock, which can be stepped by NTP or set by the user, so it is not monotonic. A duration measured by subtracting two Time.now values can come out wrong, or negative. The monotonic clock only moves forward.

Source: Process.clock_gettime

Process.clock_gettime(Process::CLOCK_MONOTONIC) returns seconds as a Float since an unspecified start, so only differences are meaningful; pass a unit (:millisecond, :microsecond, :float_millisecond, …​) as the second argument for another representation. CLOCK_PROCESS_CPUTIME_ID measures CPU time of the process, which excludes the time spent sleeping or waiting for I/O. Use Time.now for timestamps (what time is it?) and the monotonic clock for elapsed time (how long did it take?); the Benchmark library (a bundled gem in 4.0) already measures with a monotonic clock, as covered in Performance, Benchmarking and Profiling.

Until Ruby 3.3 a string literal without the magic comment was a plain mutable string. Since Ruby 3.4 it is "chilled": still mutable, but the first mutation emits a deprecation warning, preparing for a future release in which literals are frozen. Ruby 4.0 still does not freeze them by default.

Output with different flags:

Source: The frozen_string_literal directive, Warning

Without a flag Ruby 4.0.7 prints no warning at all; the deprecation category is off by default and -w or -W:deprecated turns it on (-W:no-deprecated silences it again). With --debug-frozen-string-literal the second line points at the place where the string was created. --enable-frozen-string-literal or the magic comment turns the warning into a FrozenError. Running the same file on Ruby 3.3.12 with -w prints no warning, and Ruby 3.4.11 prints the same text as 4.0.7. Use # frozen_string_literal: true at the top of every file, and +"text", String.new, dup or "#{...}" interpolation (which always builds a new, unfrozen string) when a mutable string is needed. Older books and tutorials say that literals are frozen by default from Ruby 3.4; that is incorrect, and the migration step in 3.4 is the chilled string. The details are in Strings and Literals.

case/when returns nil when nothing matches. case/in raises NoMatchingPatternError (and NoMatchingPatternKeyError for a hash pattern whose key is missing, from the one-line => form). A guard that fails counts as no match.

Output of ruby -w -Ilib f15_case_in.rb:

Source: Pattern Matching, NoMatchingPatternError

The messages differ by situation. A plain failed case reports the value and the failing check (5: String === 5 does not return true), the one-line hash pattern reports the missing key and exposes it as e.key, and a failed guard or an alternative reports only the value (-3, or [1, 2]) and sometimes just the class name (the nil case). Do not parse the message. Add an else branch, or rescue NoMatchingPatternError when failing is the intent. The boolean forms value in pattern and value => pattern are covered in Pattern Matching; in returns true or false and never raises, => raises.

@instance ||= new looks like a harmless memoization and is not atomic. Two threads can both see nil, both run new and each keep its own result, so the "singleton" exists twice. The window grows with the cost of initialize.

Output of ruby -w -Ilib f16_singleton.rb:

Source: Singleton, Mutex#synchronize

With a slow initialize the first version produces several distinct objects. The Singleton module from the standard library makes new private (private method 'new' called for class Config) and creates the instance under a lock, and an explicit Mutex around @instance ||= new does the same by hand. The GVL does not help here: it makes individual operations atomic, but a thread switch can happen between the read of @instance and the assignment, as explained in Threads and the GVL. Prefer a constant built at load time when the object is cheap, and injection of a collaborator (the shelf Catalog takes its store as a keyword argument) over a global instance.

Inside a method, returned = true creates a local variable; only self.returned = true calls the setter. Variables hold references, so assignment does not copy a string or array. Bang methods return nil when they change nothing.

Source: Assignment, String#upcase!

close sets a local and leaves the attribute false; close! assigns through self. RuboCop’s Style/RedundantSelf knows that self.returned as a reader is redundant, but it does not report the setter. b = a makes both names refer to one string, so b << ... changes a; dup makes an independent copy (a shallow one). upcase! returns nil when the receiver was already upper case, so x = text.upcase! or a chain such as text.upcase!.strip fails with NoMethodError ("undefined method 'strip' for nil"). Use the non-bang method when you want the value.

RuboCop reports many of these mistakes statically. Running the examples above with every rubocop:disable comment removed gave this result with RuboCop 1.92 and the shelf configuration.

Static checks cannot know that a value may be false, or that two threads will call the same method; those need tests and review. The cops and their configuration are described in Style, Linting and Static Analysis.

Two of the books consulted for this reference are useful for the principles of these gotchas, and both predate several changes that affect the examples above; they are cited in the bibliography and nothing from them is reproduced here.