Simplifying Ruby Code
Prefer plain data (Hash, Array, Struct, Data) and pure functions over classes
that add no state or behavior. Separate decisions from effects: a decision
takes data and returns data; an effect does I/O (database, network, files,
time). Keep them in separate methods or modules so decisions test without
mocks.
When the user asks for a review, report findings and edit nothing unless
they ask. Cite patterns by number ("Pattern 1") or by anti-pattern name.
Patterns
Command objects to module functions. A class whose only public
method is call, perform, run, or execute, holding nothing beyond
its constructor arguments, becomes a direct call or a module function
(UserCreator.new(params).call becomes User.create(params)). Keep the
object when it holds state across calls, runs a multi-step algorithm
worth naming, or must be serialized, as a background job is.
Value objects to Data, Struct, or Hash. A class that only stores
attributes, with hand-written initialize, readers, or == and no
behavior or validation:
| Use |
When |
| Hash |
Transient data, varying keys, JSON in or out |
| Struct |
Fixed attributes, mutation acceptable |
| Data |
Fixed attributes, immutable (check ruby -v >= 3.2) |
| Custom class |
Validation, invariants, or real domain behavior |
Class-method-only classes to modules. A class never instantiated,
defining only self. methods, becomes a module with module_function.
Deep inheritance to composition. More than 2 levels counting only the
project's own classes (framework and stdlib bases such as
ApplicationRecord or StandardError do not count), or an abstract base
with a single subclass.
Missing Ruby protocols. Callers unpack a collection-like or
value-like class by hand instead of it implementing each with
Enumerable, to_h, <=> with Comparable, or hash and eql?.
Mixed decisions and effects. Tests need heavy mocks, or a method
computes and writes in one body. Extract the computation into a pure
function and leave a thin method for the I/O.
Rails anti-patterns
- Service objects: a single-method, stateless service belongs in a model
method or module function (Pattern 1). Keep complex orchestration as a
service but separate decisions from effects (Pattern 6). Jobs are
legitimate objects because they serialize.
- Models: keep ActiveRecord models as classes; move business
calculations into pure functions.
- Concerns: a concern shares behavior across models; flag one used as a
dumping ground for a single model.
- Helpers: view formatting only; business rules go in a module.
- Reinvented Rails: custom DSLs or base classes that duplicate scopes,
validations, callbacks, enums, or
ActiveModel.
Plain Ruby anti-patterns
- Template methods: a base class with hook methods where a block would do.
- Builders: for objects that keyword arguments or
Data.define build
directly.
- Wrappers: classes that wrap Array, Hash, Set, or another stdlib type
and forward most calls.
- Metaprogramming:
method_missing, define_method, or instance_eval
DSLs where plain methods work.
- Dependencies: a gem pulled in for a few lines of stdlib code.
In a gem, every public constant is API that other projects may call.
Before removing or inlining a class
- Run
bash <skill-dir>/scripts/find-callers.sh <Constant> <project> for
each class.
- Exit 0: account for every
reference and require hit, and decide for
each dynamic hit whether the name it builds can be the class; that takes
reading the code, so it stays with you.
- Exit 1: no caller found. Exit 2: fix the argument. Exit 3: install the
named tool. Exit 4: report the grep error.
- A controller is also reached from
config/routes.rb by its snake_case
resource name, which the script does not search; read that file.
- In a review, drop or downgrade a finding whose callers you cannot account
for.
Review findings
Read review findings when reporting a
review: the grouping, the fields of each finding, and the closing order.
Refactoring
Get a green test baseline first. Apply one pattern at a time and run the
suite after each; on failure, fix or revert that step before continuing.
Update tests that mocked the removed layer to call the pure function or the
direct API instead.
1---2name: simplifying-ruby-code3description: Rewrites over-engineered Ruby and Rails classes (stateless service objects, behaviorless value objects, class-method-only classes, deep inheritance, needless metaprogramming) as Data, Struct, Hash, modules, or pure functions, after finding every caller and getting a green test baseline, or reports findings when asked to review. Use when the user says "simplify this Ruby", or when asked to refactor, simplify, review, or cut boilerplate from a Ruby or Rails class, value object, service object, gem, or branch diff (hand-written initialize, readers, ==, eql?, or hash; call-only classes; Struct vs Data), or when tests need heavy mocking. Not for a broad Rails tech-debt audit; use auditing-rails-tech-debt.4metadata:5 source: https://skillmd.com/skills/bostonaholic/simplifying-ruby-code6---78# Simplifying Ruby Code910Prefer plain data (Hash, Array, Struct, Data) and pure functions over classes11that add no state or behavior. Separate decisions from effects: a decision12takes data and returns data; an effect does I/O (database, network, files,13time). Keep them in separate methods or modules so decisions test without14mocks.1516When the user asks for a review, report findings and edit nothing unless17they ask. Cite patterns by number ("Pattern 1") or by anti-pattern name.1819## Patterns20211. **Command objects to module functions.** A class whose only public22 method is `call`, `perform`, `run`, or `execute`, holding nothing beyond23 its constructor arguments, becomes a direct call or a module function24 (`UserCreator.new(params).call` becomes `User.create(params)`). Keep the25 object when it holds state across calls, runs a multi-step algorithm26 worth naming, or must be serialized, as a background job is.272. **Value objects to Data, Struct, or Hash.** A class that only stores28 attributes, with hand-written `initialize`, readers, or `==` and no29 behavior or validation:3031 | Use | When |32 | ------------ | ---------------------------------------------------- |33 | Hash | Transient data, varying keys, JSON in or out |34 | Struct | Fixed attributes, mutation acceptable |35 | Data | Fixed attributes, immutable (check `ruby -v` >= 3.2) |36 | Custom class | Validation, invariants, or real domain behavior |37383. **Class-method-only classes to modules.** A class never instantiated,39 defining only `self.` methods, becomes a module with `module_function`.404. **Deep inheritance to composition.** More than 2 levels counting only the41 project's own classes (framework and stdlib bases such as42 `ApplicationRecord` or `StandardError` do not count), or an abstract base43 with a single subclass.445. **Missing Ruby protocols.** Callers unpack a collection-like or45 value-like class by hand instead of it implementing `each` with46 `Enumerable`, `to_h`, `<=>` with `Comparable`, or `hash` and `eql?`.476. **Mixed decisions and effects.** Tests need heavy mocks, or a method48 computes and writes in one body. Extract the computation into a pure49 function and leave a thin method for the I/O.5051## Rails anti-patterns5253- **Service objects:** a single-method, stateless service belongs in a model54 method or module function (Pattern 1). Keep complex orchestration as a55 service but separate decisions from effects (Pattern 6). Jobs are56 legitimate objects because they serialize.57- **Models:** keep ActiveRecord models as classes; move business58 calculations into pure functions.59- **Concerns:** a concern shares behavior across models; flag one used as a60 dumping ground for a single model.61- **Helpers:** view formatting only; business rules go in a module.62- **Reinvented Rails:** custom DSLs or base classes that duplicate scopes,63 validations, callbacks, enums, or `ActiveModel`.6465## Plain Ruby anti-patterns6667- **Template methods:** a base class with hook methods where a block would do.68- **Builders:** for objects that keyword arguments or `Data.define` build69 directly.70- **Wrappers:** classes that wrap Array, Hash, Set, or another stdlib type71 and forward most calls.72- **Metaprogramming:** `method_missing`, `define_method`, or `instance_eval`73 DSLs where plain methods work.74- **Dependencies:** a gem pulled in for a few lines of stdlib code.7576In a gem, every public constant is API that other projects may call.7778## Before removing or inlining a class7980- Run `bash <skill-dir>/scripts/find-callers.sh <Constant> <project>` for81 each class.82- Exit 0: account for every `reference` and `require` hit, and decide for83 each `dynamic` hit whether the name it builds can be the class; that takes84 reading the code, so it stays with you.85- Exit 1: no caller found. Exit 2: fix the argument. Exit 3: install the86 named tool. Exit 4: report the grep error.87- A controller is also reached from `config/routes.rb` by its snake_case88 resource name, which the script does not search; read that file.89- In a review, drop or downgrade a finding whose callers you cannot account90 for.9192## Review findings9394Read [review findings](references/review-findings.md) when reporting a95review: the grouping, the fields of each finding, and the closing order.9697## Refactoring9899Get a green test baseline first. Apply one pattern at a time and run the100suite after each; on failure, fix or revert that step before continuing.101Update tests that mocked the removed layer to call the pure function or the102direct API instead.