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

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