Common Ruby Pitfalls

Ruby's flexibility is a double-edged sword: the same expressiveness that makes it pleasant to write also makes it easy to introduce subtle bugs, especially for developers moving from more rigid languages. This topic walks through the mistakes that show up most often in real codebases and code review — mutable object sharing, string mutation surprises, nil-related crashes, and misunderstanding equality — along with the idiomatic fix for each.

A frequent bug is initializing a hash or array default value in a way that shares a single object across calls. Unlike def foo(list = []), which correctly creates a fresh array on each call, memoization patterns like @cache ||= {} combined with class-level (rather than instance-level) variables can accidentally share state across all instances of a class. Similarly, calling Array.new(3, []) creates one array object referenced three times — mutating one element mutates all three, because [] is evaluated once and reused as the fill value rather than being called per-slot.

Since Ruby 3.0, the # frozen_string_literal: true magic comment is common in gems and increasingly the default posture recommended by style guides, because it prevents accidental in-place mutation of string literals and improves performance by avoiding repeated allocation. The pitfall is forgetting that any code calling <<, gsub!, or concat on what looks like an ordinary string literal will raise FrozenError once that comment is present, so bang methods should generally be reserved for strings you know you own and created explicitly (e.g. via String.new or .dup).

Ruby has three separate equality methods, and mixing them up causes subtle bugs. == checks value equality and is the one to override for custom comparison logic. equal? checks object identity — whether two references point to the literally same object in memory — and should almost never be overridden. eql? is used internally by Hash for key comparison and additionally distinguishes types that == might treat as equal, such as 1 == 1.0 being true while 1.eql?(1.0) is false. Developers who override == but forget eql? and hash can end up with objects that behave inconsistently as hash keys.