Rails Conventions

Rails Conventions and Best Practices

Guidance for following Rails conventions, file organization, naming patterns, and "The Rails Way" for Rails 7+ applications.

Core Principles

Convention over Configuration

Rails provides sensible defaults. Follow conventions to benefit from:

• Automatic file loading and discovery
• Reduced configuration overhead
• Consistency across Rails projects
• Easier onboarding for new developers

The Rails Way

• DRY (Don't Repeat Yourself): Extract shared logic into concerns, helpers, or services
• Fat Models, Skinny Controllers: Business logic belongs in models, not controllers
• RESTful Resources: Design around resources with standard CRUD actions
• Prefer Convention: Only customize when Rails conventions don't fit

File Structure

Standard Directory Layout

app/
├── assets/           # CSS, images, fonts (managed by asset pipeline)
├── channels/         # Action Cable channels
├── components/       # ViewComponents (if used)
├── controllers/      # Request handlers
│   ├── concerns/     # Shared controller logic
│   └── api/          # API controllers (namespaced)
├── helpers/          # View helpers
├── javascript/       # JavaScript/Stimulus controllers
├── jobs/             # Background jobs
├── mailers/          # Email senders
├── models/           # ActiveRecord models
│   └── concerns/     # Shared model logic
├── services/         # Service objects (optional)
├── views/            # Templates and partials
│   ├── layouts/      # Application layouts
│   └── shared/       # Shared partials
config/
├── routes.rb         # Routing configuration
├── database.yml      # Database configuration
├── environments/     # Environment-specific settings
└── initializers/     # Startup configuration
db/
├── migrate/          # Database migrations
├── schema.rb         # Current schema (auto-generated)
└── seeds.rb          # Seed data
lib/
├── tasks/            # Rake tasks
└── generators/       # Custom generators
spec/ or test/        # Test files (mirrors app/ structure)

Naming Conventions

Models

• Class: Singular, PascalCase (User, OrderItem, BlogPost)
• File: Singular, snake_case (user.rb, order_item.rb, blog_post.rb)
• Table: Plural, snake_case (users, order_items, blog_posts)
• Foreign key: Singular model name + _id (user_id, order_item_id)

Controllers

• Class: Plural, PascalCase + Controller (UsersController, OrderItemsController)
• File: Plural, snake_case (users_controller.rb, order_items_controller.rb)
• Actions: Lowercase (index, show, new, create, edit, update, destroy)

Views

• Directory: Plural, snake_case (app/views/users/)
• Template: Action name + format + handler (index.html.erb, show.json.jbuilder)
• Partial: Underscore prefix (_form.html.erb, _user.html.erb)

Routes

• Resource: Plural (resources :users, resources :order_items)
• Singular Resource: Singular (resource :profile, resource :dashboard)

Jobs, Mailers, and Migrations

• Job class: Descriptive + Job (SendWelcomeEmailJob, ProcessPaymentJob)
• Mailer class: Descriptive + Mailer (UserMailer, OrderMailer)
• Mailer methods: Descriptive action (welcome_email, order_confirmation)
• Migration file: Timestamp + descriptive name (20240101120000_create_users.rb)
• Migration class: Descriptive PascalCase (CreateUsers, AddEmailToUsers)

Quick Reference

Follow these conventions consistently to create maintainable Rails applications that are easy to understand and extend.

Additional Resources

Reference Files

For detailed code examples and patterns, consult:

• references/restful-design.md — Standard REST actions table, custom actions, nested resources, namespace/scope patterns, and controller structure
• references/model-controller-examples.md — Association naming, polymorphic/self-referential associations, validation patterns, scope naming and chaining, callback conventions, and concern patterns

Related Skills

• service-patterns — Service objects, form objects, query objects, and interactors
• active-record-patterns — ActiveRecord query and association patterns in depth
• action-controller-patterns — Controller design patterns and advanced techniques
• rails-antipatterns — Common anti-patterns, code smells, and refactoring guidance

Converted and distributed by TomeVault — claim your Tome and manage your conversions.