Convention Over Configuration in Ruby on Rails

In this tutorial, you will learn about Convention Over Configuration in Ruby on Rails. We cover key concepts, practical examples, and best practices to help you master this topic.

Rails convention over configuration means sensible defaults for naming, structure, and behavior that eliminate configuration files and let developers focus on business logic.

What You'll Learn

By the end of this tutorial, you'll understand Rails naming conventions for models, controllers, views, and database tables, use generators effectively, and customize conventions when needed.

Why Conventions Matter

Rails conventions reduce decision fatigue. Table names derive from model names, URLs derive from controller names, and file paths derive from class names, creating predictable patterns.

Real-World Use

A team starts a new Rails app. Product model maps to products table, ProductsController maps to /products, and views live in app/views/products/ without any configuration.

Convention Path

flowchart LR
  A[Rails Conventions] --> B[Naming]
  A --> C[Structure]
  A --> D[Database]
  A --> E[Routes]
  A --> F{You Are Here}
  style F fill:#f90,color:#fff

Naming Conventions

Rails follows predictable naming patterns.

# Model: singular, CamelCase -> snake_case table
class ProductCategory  # app/models/product_category.rb
  # -> product_categories table
  has_many :products
end

# Controller: plural, CamelCase
class ProductCategoriesController  # app/controllers/product_categories_controller.rb
  def index; end
end

# Routes
# resources :product_categories
# -> /product_categories, /product_categories/:id

Directory Structure

Rails directory conventions.

# app/ - main application code
#   models/
#   controllers/
#   views/
#   helpers/
#   jobs/
#   mailers/
#   channels/
# config/ - configuration
#   routes.rb
#   database.yml
#   environments/
# db/ - database
#   migrate/
#   seeds.rb
#   schema.rb
# lib/ - reusable modules
#   tasks/ - custom rake tasks
# spec/ or test/ - tests

Generators

Rails generators scaffold based on conventions.

# Generates model, migration, controller, views, routes
rails generate scaffold Product name:string price:decimal category:references
# Generates model and migration only
rails generate model ProductCategory name:string
# Generates controller with actions
rails generate controller Products index show new create edit update destroy
# Generates mailer
rails generate mailer OrderMailer confirmation receipt

Autoloading

Zeitwerk autoloading follows file-to-class conventions.

# app/models/user.rb -> User
# app/models/admin/user.rb -> Admin::User
# app/controllers/api/v1/products_controller.rb -> Api::V1::ProductsController
# app/services/payment_processor.rb -> PaymentProcessor
# app/forms/registration_form.rb -> RegistrationForm

Common Mistakes

1. Fighting Conventions Unnecessarily

Overriding Rails defaults with manual configuration adds complexity. Use conventions unless you have a strong reason.

2. Wrong File Naming

snake_case files map to CamelCase classes. File name mismatch causes autoloading errors.

3. Singular Controller Names

Rails expects plural controller names. Singular controllers require route configuration.

4. Ignoring Generator Templates

Generators create convention-based code. Custom templates maintain conventions across the team.

5. Customizing Routes Without Convention

Overriding resourceful routes manually increases maintenance. Use resources with only/except.

Practice Questions

1. What table name does the OrderItem model map to?

order_items table.

2. What is the autoloading convention in Rails?

File path matches constant name. app/models/user.rb maps to User.

3. How do you create a namespaced model?

Place it in app/models/admin/user.rb and define as Admin::User.

4. What does rails generate scaffold create?

Model, Migration, controller, views, routes, and tests.

5. Challenge: Create a generator for a namespaced admin resource.

rails generate scaffold Admin::User name:string role:string --parent=User

FAQ

Mini Project: Build a Convention-Based App

Generate a complete resource using Rails conventions.

rails new blog_app
cd blog_app
rails generate scaffold Post title:string body:text published:boolean
rails generate scaffold Comment post:references author:string body:text
rails db:migrate
# Everything works without configuration

What's Next

Rails Routing Deep Rails RESTful Routes Rails Controllers Deep