Community Ruby on Rails Development Best Practices

Comprehensive performance and maintainability optimization guide for Ruby on Rails applications, maintained by Community. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Rails controllers, models, or views
• Optimizing ActiveRecord queries and database access patterns
• Implementing caching strategies (fragment, Russian doll, low-level)
• Building or refactoring API endpoints
• Adding Turbo Frames and Streams for interactive UIs
• Reviewing code for N+1 queries and security vulnerabilities
• Designing background jobs with Sidekiq or Active Job
• Writing or reviewing database migrations

Rule Categories by Priority

db-

ctrl-

sec-

model-

cache-

view-

api-

job-

Quick Reference

1. Database & ActiveRecord (CRITICAL)

• db-eager-load-associations

  - Eager load associations to eliminate N+1 queries

• db-add-database-indexes

  - Add database indexes on queried columns

• db-select-specific-columns

  - Select only needed columns

• db-batch-processing

  - Use find_each for large dataset iteration

• db-avoid-queries-in-loops

  - Avoid database queries inside loops

• db-use-scopes

  - Define reusable query scopes on models

• db-safe-migrations

  - Write reversible zero-downtime migrations

• db-exists-over-count

  - Use exists? instead of count for existence checks

2. Controllers & Routing (CRITICAL)

• ctrl-thin-controllers

  - Keep controllers thin by delegating to models and services

• ctrl-strong-params

  - Always use strong parameters for mass assignment

• ctrl-restful-routes

  - Follow RESTful routing conventions

• ctrl-before-action-scoping

  - Scope before_action callbacks with only/except

• ctrl-respond-to-format

  - Use respond_to for multi-format responses

• ctrl-rescue-from

  - Handle errors with rescue_from in controllers

3. Security (HIGH)

• sec-parameterized-queries

  - Never interpolate user input in SQL

• sec-strong-params-whitelist

  - Whitelist permitted params, never blacklist

• sec-authenticate-before-authorize

  - Authenticate before authorize on every request

• sec-csrf-protection

  - Enable CSRF protection for all form submissions

• sec-scope-queries-to-user

  - Scope queries to current user for authorization

4. Models & Business Logic (HIGH)

• model-validate-at-model-level

  - Validate data at the model level

• model-avoid-callback-side-effects

  - Avoid side effects in model callbacks

• model-use-service-objects

  - Extract complex logic into service objects

• model-scope-over-class-methods

  - Use scopes instead of class methods for query composition

• model-use-enums

  - Use enums for finite state fields

• model-concerns-for-shared-behavior

  - Use concerns for shared model behavior

• model-query-objects

  - Extract complex queries into query objects

5. Caching & Performance (HIGH)

• cache-fragment-caching

  - Use fragment caching for expensive view partials

• cache-russian-doll

  - Use Russian doll caching for nested collections

• cache-low-level

  - Use Rails.cache.fetch for computed data

• cache-counter-cache

  - Use counter caches for association counts

• cache-conditional-get

  - Use conditional GET with stale? for HTTP caching

6. Views & Frontend (MEDIUM-HIGH)

• view-collection-rendering

  - Use collection rendering instead of loop partials

• view-turbo-frames

  - Use Turbo Frames for partial page updates

• view-turbo-streams

  - Use Turbo Streams for real-time page mutations

• view-form-with

  - Use form_with instead of form_tag or form_for

• view-avoid-logic-in-views

  - Move display logic to helpers or presenters

7. API Design (MEDIUM)

• api-serializers

  - Use serializers for consistent JSON responses

• api-pagination

  - Always paginate collection endpoints

• api-versioning

  - Version APIs from day one

• api-error-responses

  - Return structured error responses

• api-avoid-jbuilder-hot-paths

  - Avoid Jbuilder on high-traffic endpoints

8. Background Jobs & Async (LOW-MEDIUM)

• job-idempotent-design

  - Design jobs to be idempotent

• job-small-payloads

  - Pass IDs to jobs, not serialized objects

• job-error-handling

  - Configure retry and error handling for jobs

• job-unique-jobs

  - Prevent duplicate job enqueuing

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files