DHH Ruby/Rails Style Guide

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

Patterns derived from 37signals' production applications: Basecamp, HEY, Campfire, and the open-source Fizzy SaaS project.

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

# Symbol arrays with spaces inside brackets
before_action :set_message, only: %i[ show edit update destroy ]

# Modern hash syntax exclusively
params.require(:message).permit(:body, :attachment)

# Single-line blocks with braces
users.each { |user| user.notify }

# Ternaries for simple conditionals
@room.direct? ? @room.users : @message.mentionees

# Bang methods for fail-fast
@message = Message.create!(params)
@message.update!(message_params)

# Predicate methods with question marks
@room.direct?
user.can_administer?(@message)
@messages.any?

# 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

Naming Conventions

Hotwire/Turbo Patterns

Broadcasting is model responsibility:

# In model
def broadcast_create
  broadcast_append_to room, :messages, target: "messages"
end

# In controller
@message.broadcast_replace_to @room, :messages,
  target: [ @message, :presentation ],
  partial: "messages/presentation",
  attributes: { maintain_scroll: true }

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

Architecture Preferences

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

Rails Components

• references/activerecord-tips.md - ActiveRecord query patterns, validations, associations
• references/controllers-tips.md - Controller patterns, routing, rate limiting, form objects
• references/hotwire-tips.md - Turbo Frames, Turbo Streams, Stimulus, ViewComponents
• references/turbo-morphing.md - Turbo 8 page refresh with morphing patterns
• references/activestorage-tips.md - File uploads, attachments, blob handling
• references/stimulus-catalog.md - Copy-paste-ready Stimulus controllers (clipboard, dialog, hotkey, etc.)

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/resources.md - Links to source material and further reading

Philosophy Summary

1. REST purity: 7 actions only; new controllers for variations
2. Fat models: Authorization, broadcasting, business logic in models
3. Thin controllers: 1-5 line actions; extract complexity
4. Convention over configuration: Empty methods, implicit rendering
5. Minimal abstractions: No service objects for simple cases
6. Current attributes: Thread-local request context everywhere
7. Hotwire-first: Model-level broadcasting, Turbo Streams, Stimulus
8. Readable code: Semantic naming, small methods, no comments needed