DHH Ruby/Rails Style Guide

Write Ruby and Rails code following DHH's philosophy: clarity over cleverness, convention over configuration, developer happiness above all.

Quick Reference

Controller Actions

• Only 7 REST actions: index , show , new , create , edit , update , destroy

• New behavior? Create a new controller, not a custom action

• Action length: 1-5 lines maximum

• Empty actions are fine: Let Rails convention handle rendering

class MessagesController < ApplicationController before_action :set_message, only: %i[ show edit update destroy ]

def index @messages = @room.messages.with_creator.last_page fresh_when @messages end

def show end

def create @message = @room.messages.create_with_attachment!(message_params) @message.broadcast_create end

private def set_message @message = @room.messages.find(params[:id]) end

def message_params
  params.require(:message).permit(:body, :attachment)
end

end

Private Method Indentation

Indent private methods one level under private keyword:

private def set_message @message = Message.find(params[:id]) end

def message_params
  params.require(:message).permit(:body)
end

Model Design (Fat Models)

Models own business logic, authorization, and broadcasting:

class Message < ApplicationRecord belongs_to :room belongs_to :creator, class_name: "User" has_many :mentions

scope :with_creator, -> { includes(:creator) } scope :page_before, ->(cursor) { where("id < ?", cursor.id).order(id: :desc).limit(50) }

def broadcast_create broadcast_append_to room, :messages, target: "messages" end

def mentionees mentions.includes(:user).map(&:user) end end

class User < ApplicationRecord def can_administer?(message) message.creator == self || admin? end end

Current Attributes

Use Current for request context, never pass current_user everywhere:

class Current < ActiveSupport::CurrentAttributes attribute :user, :session end

Usage anywhere in app

Current.user.can_administer?(@message)

Ruby Syntax Preferences

DHH-specific style (for general Ruby style, see ruby-coder skill):

Symbol arrays with spaces inside brackets

before_action :set_message, only: %i[ show edit update destroy ]

Expression-less case for cleaner conditionals

case when params[:before].present? @room.messages.page_before(params[:before]) when params[:after].present? @room.messages.page_after(params[:after]) else @room.messages.last_page end

Query Optimization

Prefer pluck(:name) over map(&:name) and messages.count over messages.to_a.count -- push work to the database.

StringInquirer for Predicates

Use .inquiry on string enums for readable conditionals:

class Event < ApplicationRecord def action super.inquiry end end

Clean predicate methods

event.action.completed? event.action.pending? event.action.failed?

Controller Response Patterns

Use head :no_content for updates without body, head :created for creates. Bang methods (create! , update! ) for fail-fast.

My:: Namespace for Current User Resources

Use My:: namespace for resources scoped to Current.user :

routes.rb

namespace :my do resource :profile, only: %i[ show edit update ] resources :notifications, only: %i[ index destroy ] end

app/controllers/my/profiles_controller.rb

class My::ProfilesController < ApplicationController def show @profile = Current.user end end

No index or show with ID needed—resource is implicit from Current.user .

Compute at Write Time

Perform data manipulation during saves, not during presentation:

WRONG: Compute on read

def display_name "#{first_name} #{last_name}".titleize end

CORRECT: Compute on write

before_save :set_display_name

private def set_display_name self.display_name = "#{first_name} #{last_name}".titleize end

Benefits: enables pagination, caching, and reduces view complexity.

Delegate for Lazy Loading

Use delegate to enable lazy loading through associations:

class Message < ApplicationRecord belongs_to :session delegate :user, to: :session end

Lazy loads user through session

message.user

Naming Conventions

Element Convention Example

Setter methods set_ prefix set_message , set_room

Parameter methods {model}_params

message_params

Association names Semantic, not generic creator not user

Scopes Chainable, descriptive with_creator , page_before

Predicates End with ?

direct? , can_administer?

Current user resources My:: namespace My::ProfilesController

Hotwire/Turbo Patterns

Broadcasting is model responsibility:

In model

def broadcast_create broadcast_append_to room, :messages, target: "messages" end

For detailed Hotwire patterns, use hotwire-coder skill.

Error Handling

Rescue specific exceptions, fail fast with bang methods:

def create @message = @room.messages.create_with_attachment!(message_params) @message.broadcast_create rescue ActiveRecord::RecordNotFound render action: :room_not_found end

State as Records (Not Booleans)

Track state via database records rather than boolean columns:

WRONG: Boolean columns for state

class Card < ApplicationRecord

closed: boolean, gilded: boolean columns

end card.update!(closed: true) card.closed? # Loses who/when/why

CORRECT: State as separate records

class Card < ApplicationRecord has_one :closure has_one :gilding

def close(by:) create_closure!(closed_by: by) end

def closed? closure.present? end end card.close(by: Current.user) card.closure.closed_by # Full audit trail

REST URL Transformations

Map custom actions to nested resource controllers:

Custom Action REST Resource

POST /cards/:id/close

POST /cards/:id/closure

DELETE /cards/:id/close

DELETE /cards/:id/closure

POST /cards/:id/gild

POST /cards/:id/gilding

POST /posts/:id/publish

POST /posts/:id/publication

DELETE /posts/:id/publish

DELETE /posts/:id/publication

routes.rb

resources :cards do resource :closure, only: %i[ create destroy ] resource :gilding, only: %i[ create destroy ] end

app/controllers/cards/closures_controller.rb

class Cards::ClosuresController < ApplicationController def create @card = Card.find(params[:card_id]) @card.close(by: Current.user) end

def destroy @card = Card.find(params[:card_id]) @card.closure.destroy! end end

Architecture Preferences

Traditional DHH Way

PostgreSQL SQLite (for single-tenant)

Redis + Sidekiq Solid Queue

Redis cache Solid Cache

Kubernetes Single Docker container

Service objects Fat models

Policy objects (Pundit) Authorization on User model

FactoryBot Fixtures

Boolean state columns State as records

Detailed References

For comprehensive patterns and examples, see:

Core Patterns

• references/patterns.md

• Complete code patterns with explanations

• references/palkan-patterns.md

• Namespaced model classes, counter caches, model organization order, PostgreSQL enums

• references/concerns-organization.md

• Model-specific vs common concerns, facade pattern

• references/delegated-types.md

• Polymorphism without STI problems

• references/recording-pattern.md

• Unifying abstraction for diverse content types

• references/filter-objects.md

• PORO filter objects, URL-based state, testable query building

• references/database-patterns.md

• UUIDv7, hard deletes, state as records, counter caches, indexing

Rails Components

• references/activerecord-tips.md

• ActiveRecord query patterns, validations, associations

• references/controllers-tips.md

• Controller patterns, routing, rate limiting, form objects

• references/activestorage-tips.md

• File uploads, attachments, blob handling

Hotwire

• references/hotwire-tips.md

• Turbo Frames, Turbo Streams, ViewComponents

• references/turbo-morphing.md

• Turbo 8 page refresh with morphing patterns

• references/stimulus-catalog.md

• Copy-paste-ready Stimulus controllers (clipboard, dialog, hotkey, etc.)

• Also see: hotwire-coder , stimulus-coder , viewcomponent-coder skills for detailed patterns

Frontend

• references/css-architecture.md
• Native CSS patterns (layers, OKLCH, nesting, dark mode)

Authentication & Multi-Tenancy

• references/passwordless-auth.md

• Magic link authentication, sessions, identity model

• references/multi-tenancy.md

• Path-based tenancy, cookie scoping, tenant-aware jobs

Infrastructure & Integrations

• references/webhooks.md

• Secure webhook delivery, SSRF protection, retry strategies

• references/caching-strategies.md

• Russian Doll caching, Solid Cache, cache analysis

• references/config-tips.md

• Configuration, logging, deployment patterns

• references/structured-events.md

• Rails 8.1 Rails.event API for structured observability

• references/resources.md

• Links to source material and further reading

Philosophy Summary

• REST purity: 7 actions only; new controllers for variations

• Fat models: Authorization, broadcasting, business logic in models

• Thin controllers: 1-5 line actions; extract complexity

• Convention over configuration: Empty methods, implicit rendering

• Minimal abstractions: No service objects for simple cases

• Current attributes: Thread-local request context everywhere

• Hotwire-first: Model-level broadcasting, Turbo Streams, Stimulus

• Readable code: Semantic naming, small methods, no comments needed

Success Indicators

Code aligns with DHH style when:

• Controllers map CRUD verbs to resources (no custom actions)

• Models use concerns for horizontal behavior sharing

• State uses records instead of boolean columns

• Abstractions remain minimal (no unnecessary service objects)

• Database backs solutions (Solid Queue/Cache, not Redis)

• Turbo/Stimulus handle all interactivity

• Authorization lives on User model (can_*? methods)

• Current attributes provide request context

• Scopes follow naming conventions (chronologically , with_* , etc.)

• Uses pluck over map for attribute extraction

• Current user resources use My:: namespace

• Data computed at write time, not presentation