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

Priority Category Impact Prefix

1 Database & ActiveRecord CRITICAL db-

2 Controllers & Routing CRITICAL ctrl-

3 Security HIGH sec-

4 Models & Business Logic HIGH model-

5 Caching & Performance HIGH cache-

6 Views & Frontend MEDIUM-HIGH view-

7 API Design MEDIUM api-

8 Background Jobs & Async LOW-MEDIUM 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

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information