The ALA Checklist for objects: the OO and Ruby editions

October 5, 2026 · ALA · checklist · Ruby · Rails · OO

The ALA Checklist came in two editions: a general one for functional languages and an Elixir one. Spray writes almost every example in C#, though, and says plainly that “ALA is object oriented, but its object oriented in a much more disciplined way than conventional object orientation. That’s because peer classes may NOT have associations” (Summary). So the next two editions read the same eleven rules for classes and objects: an object-oriented edition for any OO language, and a Ruby and Rails edition with code for each technique. The rules, notation and citations don’t change. What changes is what a rule looks like when the unit is a class and the edges are everything a class can know about another.

This post is about that difference, and about the one that matters most in practice: Elixir gave R2 and R4 almost for free, because nothing is mutable. An OO language makes them the default failure.

Every way a class can know another is an edge

In Elixir, R1 was mostly about calls: a module naming another module’s function. In an OO language the OO edition lists eight kinds of edge, because R1 and R9 judge them differently:

EdgeExampleRule
a callShipping.cost(...)R1
an instantiationHydrogen.new inside OxygenR1 (Spray’s §7.5 defect: the new belongs in Water)
a field, parameter or return typed by a peer@inventory : InventoryR1, and R9 when it’s a port
a superclassclass Truck < VehicleR1 (the inheritance edge; compose instead, §2.1.3)
an implemented interface or included mixininclude PayableR9 (a paradigm port is fine; an owned one is a defect)
a constant or nested typeOrder::STATUSESR1, R5
reopening or patching a lower class from abovea monkey patch from application codeR1
a container registration or locator lookupImport["payments.gateway"]R9 (“no endpoints”, §4.4.2)

The one that surprised me is that injection doesn’t help. Spray: “Simple dependency injection or otherwise passing an object into another object doesn’t remove the association between their respective classes… in ALA you are not allowed to know about a class in the same layer, not even its interface. Not even a base class” (§2.1.3). Injection changes who chooses the instance, not what the class knows. The field has to be typed by a programming-paradigm interface from a lower layer, which is R9.

Ports on a class, and the two interfaces

Spray’s class has two interfaces. The main interface is its constructor and configuration, “only used to instantiate and configure the class from a higher layer. It is never used to actually use the class to do its work” (§2.3.4). Everything else goes through ports: a private field typed by a paradigm interface (an accepted port, where it sends) or an implemented paradigm interface (a provided port, what it receives). “What makes it a port is the abstraction level of the interface” (Summary).

Ruby has no interfaces or field types, so the Ruby edition’s Foundation declares ports with class macros instead. output is a private instance variable the wiring fills; input is a handler that stays private, so port methods never join the class’s public interface (§4.4.4); wire_to returns the source and wire_in the target for fluent wiring (§5.8.3), and a wire to a port that doesn’t exist raises at wiring time (§2.2):

class Wishlist
  include Foundation::Ports
  output :added, ProgrammingParadigms::DataFlow
  input(:add, ProgrammingParadigms::DataFlow) do |product_id|
    @ids << product_id
    @added.push(product_id)
  end
  def initialize = @ids = []
end

# the composition
wishlist = Wishlist.new
wishlist.wire_to(notifier, from: :added, to: :notify)
wishlist.on(:added) { |id| flash[:notice] = "Saved" }   # Spray's lambda at the wire (§6.17.4)

The whole Foundation is about ninety lines, and it is the same ninety lines in both Ruby variants.

Duck typing doesn’t remove the knowledge

A question a Rubyist asks straight away: if nothing declares a type, what is an “owned interface”? The Ruby edition’s answer is that a port’s paradigm is the set of messages it may send (push, send_event, request), defined once in the Programming Paradigms layer. A class that sends a peer’s own messages to whatever it was given (gateway.charge(order), cart.line_items) is written to that peer’s design whether or not anything declares it. Spray’s reasons already cover it: a dependency exists “if there is a reference to something named inside the class or interface” (§3.4), and “Even if Light is injected into Switch by a higher entity called System, Switch still knows the specific interface of a light (LightOn(), LightOff())” (§3.3.1). Duck typing removes the declaration, not the knowledge. respond_to?(:charge) on a collaborator is the tell.

What Elixir had for free

This is the section the Elixir editions never needed. Three rules change weight when values are mutable references by default.

R2, wires meet only at the top. In Elixir a value handed to two features can’t become a back channel: each gets its own copy. In Ruby, passing one object to two peers, or keeping a returned object its producer still holds, creates the shared *pN without anyone meaning to. A shared Order that the cart fills in and checkout updates is the classic case, and so is a getter that hands out a live internal collection for a peer to change: “objects effectively know about the existence of another object’s state and collaborate with that state. They reach into each other’s data indirectly” (§3.10). The Ruby edition’s techniques are the ones Spray gives in §3.9: configuration and wiring fields “immutable after they are set”; values, not live references, on wires (Data.define, frozen hashes, a Money value); state that belongs to no concept made into a wired State<T> abstraction. A clean R2 says more about an OO design than about a functional one, because the language did nothing to help.

R4, state with its owner. Elixir forced the question “where does the state go?” because a filter’s memory had to be threaded somewhere. Objects answer it too easily: an instance variable is right there, and so is the temptation to let the composition keep one too (@total computed in a controller) or to let a “manager” hold several concepts’ state that features reach into. Spray’s four reasons for an object’s fields (§3.10) sort them: ports, configuration, the abstraction’s own state, and, in a State<T>, state that belongs to no other code. Only the last two change. And threads: with mutable state, “it would be prudent for only one thread to be using each instance” (§3.9), and locks don’t go inside the class, because they’d couple it to callers’ threading (§3.10.2). In Rails that becomes a concrete rule: build stateful instances per request, because Puma serves requests on several threads, and keep long-lived state in a store abstraction.

R10, no shared entity. Elixir’s structs made a shared entity visible as a struct two features pattern-matched. An OO codebase usually has a class per business noun, often persistent, that every feature reads and writes, which is exactly Clean Architecture’s entity, and Spray rejects it: entities “are an easy place to just add all fields to do with an identity. They will tend to hold some fields that, although they associate with an identify, really belong to separate use cases” (§6.17.2). A persistent model class is both a shared type and a store reached by name, so it fails R10, R1 and R9 at once. The fix is his: share the identity key, give each use case private data stored against it, and reach the table through an abstraction of persistence the composition configures (§6.19).

The rest of the OO material is gathered in one section of the OO edition, twenty-one points from the Summary, §2.1.3, §3.9–3.10, §6.14.5, §6.17 and elsewhere, each with what it means in an OO language and the rule it supports. The ones that bite: no inheritance, compose and delegate explicitly instead (§7.16, so a delegating method is an expected shape, not proliferation); wiring by hand or by a reflection operator the composition calls, never by a container that matches types (“There is no place where you can see the wiring explicitly. This is really bad”, §3.10.1); and a factory port when instances must be made at run time (§5.8.5).

Words, and whose they are

The R3 question a Rails team asks first: does ALA really mean the text on the page is passed in as configuration? Spray’s practice says yes in every example (new Display(label: "Temperature"), new Menu("File"), a wizard’s titles, a LiteralString("Connected to device") wired into a status bar; “only requires a label and a binding to an action”, §7.14), and his UI abstractions carry no words of their own. He never says it as a rule; the checklist does, from §1.6.3 and §2.4. What makes it workable is the exception the checklist now states: a word the abstraction’s domain owns stays, a word the product owns moves. A retail stock badge’s “Out of stock” is retail’s; “Your cart is empty.” is this store’s. The reviewer’s test is would another product in the same domain keep this word? The Ruby linter reads the decision from the code:

class StockBadge
  INHERENT_LABELS = { in_stock: "In stock", low_stock: "Only %{n} left!", out_of_stock: "Out of stock" }.freeze
end

# ala:accept r3 -- the carrier's own name, not this store's wording
def label = "Standard"

Strings under an INHERENT_ constant are never product text to R3; an # ala:accept CHECK comment takes the next line (or lines=N) out of one named check, and --list-accepted prints every declaration and acceptance, with the ones that no longer cover anything. The rule stays; the judgement is written where the code is.

The page’s layout is the product’s

R11 says the composition holds no logic. It does not say the composition is generic, and a page’s layout is the least generic thing in the app on purpose. Spray writes the layout in the composition, in the UI-layout paradigm (“The order of the fanout of relationships sets the order that the elements appear”, §4.12), and keeps it with the story: “the layout of the UI is a small amount of information… kept together, encapsulated inside a feature. Instead, the UI is composed from Domain UI abstractions” (§7.14). In Rails that is the page template:

<div class="grid items-start gap-8 lg:grid-cols-[1fr_22rem]">
  <section class="rounded-2xl border bg-white p-6" data-controller="tabs">
    <%= render "elements/tabs", tabs: @tabs %>
    <%= render partial: "components/cart_line", collection: @s.rows, as: :row, locals: { t: @texts[:cart] } %>
  </section>
  <aside class="lg:sticky lg:top-6">
    <%= render "components/cart_summary", summary: @s.summary, t: @texts[:cart] %>
    <%= render "components/shipping_selector", summary: @s.summary, url: shipping_cart_path %>
  </aside>
</div>

The grid, the sticky aside, the order and the gaps are the page’s own and not a finding; the partials are domain UI abstractions, and the classes inside _cart_summary are its own style (§7.14), also not a finding. What is a finding, with the rule: an each or a comparison in the page (R11; render collection: and a row that carries its booleans), a partial calling a model or a route helper (a data source or the app’s routes inside a UI abstraction), a partial rendering a peer partial (R1; the page places both, or the inner one is declared an element), and words in a partial’s markup (R3; the page passes t: in). V02 is this template.

Where Rails’ pieces sit

The Ruby edition ends with a table that answers the question every Rails developer asks first. The short version:

Rails pieceALA roleMeets the rules when
controller actionapplication: a wireit decodes params, pushes one input of a composition, and renders or redirects
a composition class (Screens::Cart)applicationit instantiates, configures and wires, built per request
views and partialsUI-layout wiring; reusable partials are UI domain abstractionsa template places components and passes data in; it never loops, compares or calls a model
ApplicationRecord modelspersistence for one feature, or the shared identityeach belongs to one feature and is reached as a configured store
validationsintrinsic constraintsmessages come from the composition or I18n keys it owns
concerns, STIa paradigm or Foundation modulenot code shared among a few peers, not a hierarchy per use case
Current attributesapplicationthe composition reads them and passes values down
Turbo Streams, Action Cableglobal event names (§4.7.4)the composition subscribes and owns the stream names
Active Joban asynchronous execution modela paradigm-layer job delivers a push to an input the composition named
DI containersnot usedthey resolve collaborators by key (§3.10.1)

Because Application reads ambiguously beside Rails.application, the edition names compositions Screens::.

Active Record is the resource-centric case: a model with associations, callbacks and every feature’s scopes attached is the entity Spray rejects (§6.17.2), and the usable slice is one model per feature’s private table, keyed by an identity, with its intrinsic validations inside, reached as a configured store. That is V02’s cart_items, saved_items and wishlist_items, which share a product_id and nothing else. The Elixir edition reads Ash the same way, piece by piece, in its own post. Zeitwerk gives the layers’ namespaces from app/ala/’s subdirectories.

The tiers, and what the linter can see

The enforcement tiers are the same as the Elixir edition’s, with the OO forms added to the required set: R1 now includes fields and parameters typed by a peer, a peer created with new, and a superclass in your own layers; R9 includes owned interfaces, abstract base classes used as ports, and container or locator wiring. The honest limit is also stated: in a dynamically typed language, field and parameter types and many call targets are invisible statically, so R1 and R9 are weaker unless a tool also runs a wiring-time check. The Ruby linter is what that limit looks like in practice.

The checklist repository is ala_checklist; the OO and Ruby editions sit beside the functional and Elixir ones.

← all posts