Rails Classic Coding Style

Core Workflow

1. Use generators first —

   rails g model

   ,

   rails g controller

   ,

   rails g migration

   . Generators produce correct file structure, test stubs, and route entries in one shot.
2. Implementation order — models → controllers → views → tests.
3. Ship, Validate, Refine — prototype to production, learn from real usage.
4. Let it crash — use bang methods, let Rails handle RecordInvalid with 422s.

Guardrails

• No service objects — use domain models namespaced under

  app/models/

• No custom controller actions — create new resources instead (REST mapping)
• No RSpec, no factory_bot — Minitest with fixtures only
• No Redis — Solid Queue, Solid Cache, Solid Cable
• No

  strftime

  in views — custom DATE_FORMATS in initializers
• Callbacks only for derived data and async dispatch — never business logic
• Database constraints over model validations for hard guarantees
• Pass IDs to jobs, not objects

Conventions Quick Reference

Naming

• Verbs for state changes:

  card.close

  ,

  board.publish

• Predicates from record presence:

  card.closed?

  ,

  card.golden?

• Concerns as adjectives:

  Closeable

  ,

  Publishable

  ,

  Watchable

• Controllers as nouns:

  Cards::ClosuresController

• Scopes as business terms:

  scope :active

  ,

  scope :chronologically

REST Mapping

POST /cards/:id/closure

POST /cards/:id/archival

POST /boards/:id/watching

Models — State as Records

class Card::Closure < ApplicationRecord
  belongs_to :card
  belongs_to :creator, class_name: "User"
end

module Closeable
  extend ActiveSupport::Concern

  included do
    has_one :closure, dependent: :destroy
  end

  def closed? = closure.present?
  def close(creator: Current.user) = create_closure!(creator: creator)
  def reopen = closure&.destroy
end

# Querying
Card.joins(:closure)          # closed
Card.where.missing(:closure)  # open

Concerns — Horizontal Behavior

class Card < ApplicationRecord
  include Assignable, Closeable, Golden, Watchable, Searchable
end

POROs Under Model Namespace

# app/models/event/description.rb
class Event::Description
  def initialize(event) = @event = event
  def to_s = # ...
end

Validations

# Model — minimal
class User < ApplicationRecord
  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
  normalizes :email, with: ->(e) { e.strip.downcase }
end

# Migration — hard constraints
add_index :users, :email, unique: true
add_foreign_key :cards, :boards

Association Design

has_and_belongs_to_many

has_many :through

has_many :through

polymorphic: true

delegated_type

:dependent

has_many

has_one

:inverse_of

Rails 7.1+ Patterns

# Delegated types
class Message < ApplicationRecord
  delegated_type :messageable, types: %w[Comment Reply Announcement]
end

# store_accessor for JSON/JSONB
class User < ApplicationRecord
  store_accessor :settings, :theme, :notifications_enabled
end

Database

# UUIDs (UUIDv7 — time-sortable)
create_table :cards, id: :uuid do |t|
  t.references :board, type: :uuid, foreign_key: true
end

# Counter caches
class Comment < ApplicationRecord
  belongs_to :card, counter_cache: true
end

# Default values with Current
class Card < ApplicationRecord
  belongs_to :creator, class_name: "User", default: -> { Current.user }
end

Controllers

module CardScoped
  extend ActiveSupport::Concern
  included { before_action :set_card }

  private
    def set_card
      @card  = Card.find(params[:card_id])
      @board = @card.board
    end
    def render_card_replacement
      render turbo_stream: turbo_stream.replace(@card)
    end
end

class Cards::ClosuresController < ApplicationController
  include CardScoped
  def create  = @card.close   && render_card_replacement
  def destroy = @card.reopen  && render_card_replacement
end

Current Attributes

class Current < ActiveSupport::CurrentAttributes
  attribute :session, :user, :account, :request_id
  delegate :user, to: :session, allow_nil: true
end

Background Jobs

module Watchable
  def notify_watchers_later = NotifyWatchersJob.perform_later(self)
  def notify_watchers
    watchers.each { |w| WatcherMailer.notification(w, self).deliver_later }
  end
end

class NotifyWatchersJob < ApplicationJob
  def perform(card) = card.notify_watchers
end

View Helpers

strftime

# config/initializers/date_formats.rb
Date::DATE_FORMATS[:default]    = "%d.%m.%Y"
Time::DATE_FORMATS[:default]    = "%d.%m.%Y %H:%M"
Time::DATE_FORMATS[:time_only]  = "%H:%M"

active_link_to

Testing

• Minitest with fixtures, integration tests for controllers
• Test observable behavior, not implementation
• Don't mock what you can test for real
• VCR for external APIs

Preferred Stack

Gem Selection

1. Can vanilla Rails do this?
2. Is it the app's core concern? If yes, own the code
3. Does it add infrastructure? Database-backed alternatives exist
4. Is the complexity worth it?
5. Is it from someone you trust?

Deep Reference Files

• Design patterns (form objects, query objects, strategies, etc.): reference/patterns.md
• Anti-patterns and code smells: reference/anti-patterns.md, reference/smells.md
• Refactoring recipes: reference/refactorings/ (002–010)
• Testing guide: reference/shared/testing.md
• Hotwire (Turbo + Stimulus): reference/shared/hotwire.md
• Background jobs + Continuations: reference/shared/jobs.md
• State machines (AASM): reference/shared/state_machines.md
• Callbacks scoring + extraction: reference/shared/callbacks.md
• Authorization (Pundit): reference/shared/authorization.md
• Notifications (Noticed): reference/shared/notifications.md
• Instrumentation / EventReporter: reference/shared/instrumentation.md
• Components (Phlex): reference/shared/components.md
• Serializers (API JSON): reference/shared/serializers.md
• Architecture layers: reference/shared/architecture.md
• Gem recommendations: reference/toolbelt.md

hwc-*