= Rails Style Guide :idprefix: :idseparator: - :sectanchors: :sectlinks: :toc: preamble :toclevels: 1 ifndef::backend-pdf[] :toc-title: pass:[
== Introduction
By https://github.com/bbatsov[Bozhidar Batsov]
[quote]
Role models are important.
-- Officer Alex J. Murphy / RoboCop
ifdef::env-github[] TIP: You can find a beautiful version of this guide with much improved navigation at https://rails.rubystyle.guide. endif::[]
The goal of this guide is to present a set of best practices and style prescriptions for Ruby on Rails development. It's a complementary guide to the already existing community-driven https://github.com/rubocop/ruby-style-guide[Ruby coding style guide].
This Rails style guide recommends best practices so that real-world Rails programmers can write code that can be maintained by other real-world Rails programmers. A style guide that reflects real-world usage gets used, and a style guide that holds to an ideal that has been rejected by the people it is supposed to help risks not getting used at all - no matter how good it is.
The guide is separated into several sections of related rules. I've tried to add the rationale behind the rules (if it's omitted I've assumed it's pretty obvious).
I didn't come up with all the rules out of nowhere - they are mostly based on my extensive career as a professional software engineer, feedback and suggestions from members of the Rails community and various highly regarded Rails programming resources.
NOTE: Some of the advice here is applicable only to recent versions of Rails.
You can generate a PDF copy of this guide using https://asciidoctor.org/docs/asciidoctor-pdf/[AsciiDoctor PDF], and an HTML copy https://asciidoctor.org/docs/convert-documents/#converting-a-document-to-html[with] https://asciidoctor.org/#installation[AsciiDoctor] using the following commands:
asciidoctor-pdf -a allow-uri-read README.adoc
Install the rouge gem to get nice syntax highlighting in the generated document.
====
Translations of the guide are available in the following languages:
TIP: https://github.com/rubocop/rubocop[RuboCop], a static code analyzer (linter) and formatter, has a https://github.com/rubocop/rubocop-rails[`rubocop-rails`] extension, based on this style guide.
== Configuration
=== Config Initializers [[config-initializers]]
Put custom initialization code in config/initializers.
The code in initializers executes on application startup.
=== Gem Initializers [[gem-initializers]]
Keep initialization code for each gem in a separate file with the same name as the gem, for example carrierwave.rb, active_admin.rb, etc.
=== Dev/Test/Prod Configs [[dev-test-prod-configs]]
Adjust accordingly the settings for development, test and production environment (in the corresponding files under config/environments/)
Mark additional assets for precompilation (if any):
=== App Config [[app-config]]
Keep configuration that's applicable to all environments in the config/application.rb file.
=== Load Rails Config Defaults [[config-defaults]]
When upgrading to a newer Rails version, your application's configuration setting will remain on the previous version. To take advantage of the latest recommended Rails practices, the config.load_defaults setting should match your Rails version.
=== Staging Like Prod [[staging-like-prod]]
Avoid creating additional environment configurations than the defaults of development, test and production.
If you need a production-like environment such as staging, use environment variables for configuration options.
=== YAML Config [[yaml-config]]
Keep any additional configuration in YAML files under the config/ directory.
Since Rails 4.2 YAML configuration files can be easily loaded with the new config_for method:
== Routing
=== Member Collection Routes [[member-collection-routes]]
When you need to add more actions to a RESTful resource (do you really need them at all?) use member and collection routes.
get 'subscriptions/:id/unsubscribe' resources :subscriptions
resources :subscriptions do get 'unsubscribe', on: :member end
get 'photos/search' resources :photos
=== Many Member Collection Routes [[many-member-collection-routes]]
If you need to define multiple member/collection routes use the alternative block syntax.
resources :subscriptions do member do get 'unsubscribe'
end end
resources :photos do collection do get 'search'
=== Nested Routes [[nested-routes]]
Use nested routes to express better the relationship between Active Record models.
class Post < ApplicationRecord has_many :comments end
class Comment < ApplicationRecord belongs_to :post end
=== Shallow Routes [[shallow-routes]]
If you need to nest routes more than 1 level deep then use the shallow: true option.
This will save user from long URLs posts/1/comments/5/versions/7/edit and you from long URL helpers edit_post_comment_version.
=== Namespaced Routes [[namespaced-routes]]
Use namespaced routes to group related actions.
namespace :admin do
=== No Wild Routes [[no-wild-routes]]
Never use the legacy wild controller route. This route will make all actions in every controller accessible via GET requests.
=== No Match Routes [[no-match-routes]]
Don't use match to define any routes unless there is need to map multiple request types among [:get, :post, :patch, :put, :delete] to a single action using :via option.
== Controllers
=== Skinny Controllers [[skinny-controllers]]
Keep the controllers skinny - they should only retrieve data for the view layer and shouldn't contain any business logic (all the business logic should naturally reside in the model).
=== One Method [[one-method]]
Each controller action should (ideally) invoke only one method other than an initial find or new.
=== Shared Instance Variables [[shared-instance-variables]]
Minimize the number of instance variables passed between a controller and a view.
=== Lexically Scoped Action Filter [[lexically-scoped-action-filter]]
Controller actions specified in the option of Action Filter should be in lexical scope. The ActionFilter specified for an inherited action makes it difficult to understand the scope of its impact on that action.
class UsersController < ApplicationController before_action :require_login, only: :export end
class UsersController < ApplicationController before_action :require_login, only: :export
== Controllers: Rendering [[rendering]]
=== Inline Rendering [[inline-rendering]]
Prefer using a template over inline rendering.
class ProductsController < ApplicationController def index render inline: "<% products.each do |p| %>
<%= p.name %>
<% end %>", type: :erb end end<%= render partial: 'product', collection: products %>
<%= product.name %>
<%= product.price %>
=== Plain Text Rendering [[plain-text-rendering]]
Prefer render plain: over render text:.
text/html... render text: 'Ruby!' ...
... render text: 'Ruby!', content_type: 'text/plain' ...
=== HTTP Status Code Symbols [[http-status-code-symbols]]
Prefer https://gist.github.com/mlanett/a31c340b132ddefa9cca[corresponding symbols] to numeric HTTP status codes. They are meaningful and do not look like "magic" numbers for less known HTTP status codes.
... render status: 403 ...
== Models
=== Model Classes [[model-classes]]
Introduce non-Active Record model classes freely.
=== Meaningful Model Names [[meaningful-model-names]]
Name the models with meaningful (but short) names without abbreviations.
=== Non-ActiveRecord Models [[non-activerecord-models]]
If you need objects that support ActiveRecord-like behavior (like validations) without the database functionality, use ActiveModel::Model.
class Message include ActiveModel::Model
attr_accessor :name, :email, :content, :priority
Starting with Rails 6.1, you can also extend the attributes API from ActiveRecord using ActiveModel::Attributes.
class Message include ActiveModel::Model include ActiveModel::Attributes
attribute :name, :string attribute :email, :string attribute :content, :string attribute :priority, :integer
=== Model Business Logic [[model-business-logic]]
Unless they have some meaning in the business domain, don't put methods in your model that just format your data (like code generating HTML). These methods are most likely going to be called from the view layer only, so their place is in helpers. Keep your models for business logic and data-persistence only.
== Models: Active Record [[activerecord]]
=== Keep Active Record Defaults [[keep-ar-defaults]]
Avoid altering Active Record defaults (table names, primary key, etc) unless you have a very good reason (like a database that's not under your control).
=== Always append to ignored_columns [[append-ignored-columns]]
Avoid setting ignored_columns. It may overwrite previous assignments and that is almost always a mistake. Prefer appending to the list instead.
class Transaction < ApplicationRecord
self.ignored_columns = %i[legacy]
=== Enums [[enums]]
Prefer using the hash syntax for enum. Array makes the database values implicit
& any insertion/removal/rearrangement of values in the middle will most probably
lead to broken code.
class Transaction < ApplicationRecord
enum type: %i[credit debit]
=== Macro Style Methods [[macro-style-methods]]
Group macro-style methods (has_many, validates, etc) in the beginning of the class definition.
class User < ApplicationRecord
default_scope { where(active: true) }
COLORS = %w(red green blue)
attr_accessor :formatted_date_of_birth
attr_accessible :login, :first_name, :last_name, :email, :password
enum role: { user: 0, moderator: 1, admin: 2 }
belongs_to :country
has_many :authentications, dependent: :destroy
validates :email, presence: true validates :username, presence: true validates :username, uniqueness: { casesensitive: false } validates :username, format: { with: /\A[A-Za-z][A-Za-z0-9.-]{2,19}\z/ } validates :password, format: { with: /\A\S{8,128}\z/, allow_nil: true }
before_save :cook before_save :update_username_lower
=== has_many :through [[has-many-through]]
Prefer has_many :through to has_and_belongs_to_many.
Using has_many :through allows additional attributes and validations on the join model.
class User < ApplicationRecord has_and_belongs_to_many :groups end
class Group < ApplicationRecord has_and_belongs_to_many :users end
class User < ApplicationRecord has_many :memberships has_many :groups, through: :memberships end
class Membership < ApplicationRecord belongs_to :user belongs_to :group end
=== Read Attribute [[read-attribute]]
Prefer self[:attribute] over read_attribute(:attribute).
def amount read_attribute(:amount) * 100 end
=== Write Attribute [[write-attribute]]
Prefer self[:attribute] = value over write_attribute(:attribute, value).
def amount write_attribute(:amount, 100) end
=== New-style Validations [[new-style-validations]]
Always use the http://thelucid.com/2010/01/08/sexy-validation-in-edge-rails-rails-3/["new-style" validations].
validates_presence_of :email validates_length_of :email, maximum: 100
=== Custom Validation Methods
When naming custom validation methods, adhere to the simple rules:
validate :method_name reads like a natural statementvalidate :expiration_date_cannot_be_in_the_past validate :discount_cannot_be_greater_than_total_value validate :ensure_same_topic_is_chosen
validate :validate_birthday_in_past validate :validate_sufficient_quantity validate :must_have_owner_with_no_other_items validate :must_have_shipping_units
=== Single-attribute Validations [[single-attribute-validations]]
To make validations easy to read, don't list multiple attributes per validation.
validates :email, :password, presence: true validates :email, length: { maximum: 100 }
=== Custom Validator File [[custom-validator-file]]
When a custom validation is used more than once or the validation is some regular expression mapping, create a custom validator file.
class Person validates :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+.)+[a-z]{2,})\z/i } end
class EmailValidator < ActiveModel::EachValidator def validate_each(record, attribute, value) record.errors[attribute] << (options[:message] || 'is not a valid email') unless value =~ /\A([^@\s]+)@((?:[-a-z0-9]+.)+[a-z]{2,})\z/i end end
=== App Validators [[app-validators]]
Keep custom validators under app/validators.
=== Custom Validators Gem [[custom-validators-gem]]
Consider extracting custom validators to a shared gem if you're maintaining several related apps or the validators are generic enough.
=== Named Scopes [[named-scopes]]
Use named scopes freely.
class User < ApplicationRecord scope :active, -> { where(active: true) } scope :inactive, -> { where(active: false) }
=== Named Scope Class [[named-scope-class]]
When a named scope defined with a lambda and parameters becomes too complicated, it is preferable to make a class method instead which serves the same purpose of the named scope and returns an ActiveRecord::Relation object.
Arguably you can define even simpler scopes like this.
=== Callbacks Order [[callbacks-order]]
Order callback declarations in the order in which they will be executed. For reference, see https://guides.rubyonrails.org/active_record_callbacks.html#available-callbacks[Available Callbacks].
class Person after_commit :after_commit_callback before_validation :before_validation_callback end
=== Beware Skip Model Validations [[beware-skip-model-validations]]
Beware of the behavior of the https://guides.rubyonrails.org/active_record_validations.html#skipping-validations[following] methods. They do not run the model validations and could easily corrupt the model state.
Article.first.decrement!(:view_count) DiscussionBoard.decrement_counter(:post_count, 5) Article.first.increment!(:view_count) DiscussionBoard.increment_counter(:post_count, 5) person.toggle :active product.touch Billing.update_all("category = 'authorized', author = 'David'") user.update_attribute(:website, 'example.com') user.update_columns(last_request_at: Time.current) Post.update_counters 5, comment_count: -1, action_count: 1
=== User-friendly URLs [[user-friendly-urls]]
Use user-friendly URLs.
Show some descriptive attribute of the model in the URL rather than its id.
There is more than one way to achieve this.
==== Override the to_param Method of the Model
This method is used by Rails for constructing a URL to the object.
The default implementation returns the id of the record as a String.
It could be overridden to include another human-readable attribute.
In order to convert this to a URL-friendly value, parameterize should be called on the string.
The id of the object needs to be at the beginning so that it can be found by the find method of Active Record.
==== friendly_id Gem
It allows creation of human-readable URLs by using some descriptive attribute of the model instead of its id.
Check the https://github.com/norman/friendly_id[gem documentation] for more information about its usage.
=== find_each [[find-each]]
Use find_each to iterate over a collection of AR objects.
Looping through a collection of records from the database (using the all method, for example) is very inefficient since it will try to instantiate all the objects at once.
In that case, batch processing methods allow you to work with the records in batches, thereby greatly reducing memory consumption.
Person.all.each do |person| person.do_awesome_stuff end
Person.where('age > 21').each do |person| person.party_all_night! end
Person.find_each do |person| person.do_awesome_stuff end
=== before_destroy [[before_destroy]]
Since https://github.com/rails/rails/issues/3458[Rails creates callbacks for dependent associations], always call before_destroy callbacks that perform validation with prepend: true.
has_many :roles, dependent: :destroy
before_destroy :ensure_deletable
def ensure_deletable raise "Cannot delete super admin." if super_admin? end
has_many :roles, dependent: :destroy
before_destroy :ensure_deletable, prepend: true
=== has_many/has_one Dependent Option [[has_many-has_one-dependent-option]]
Define the dependent option to the has_many and has_one associations.
class Post < ApplicationRecord has_many :comments end
=== save! [[save-bang]]
When persisting AR objects always use the exception raising bang! method or handle the method return value.
This applies to create, save, update, destroy, first_or_create and find_or_create_by.
user.create(name: 'Bruce')
user.save
user.create!(name: 'Bruce')
bruce = user.create(name: 'Bruce') if bruce.persisted? ... else ... end
user.save!
== Models: Active Record Queries [[activerecord-queries]]
=== Avoid Interpolation [[avoid-interpolation]]
Avoid string interpolation in queries, as it will make your code susceptible to SQL injection attacks.
Client.where("orders_count = #{params[:orders]}")
=== Named Placeholder [[named-placeholder]]
Consider using named placeholders instead of positional placeholders when you have more than 1 placeholder in your query.
Client.where( 'orders_count >= ? AND country_code = ?', params[:min_orders_count], params[:country_code] )
=== find [[find]]
Prefer find over where.take!, find_by!, and find_by_id! when you need to retrieve a single record by primary key id and raise ActiveRecord::RecordNotFound when the record is not found.
User.where(id: id).take!
User.find_by_id!(id)
User.find_by!(id: id)
=== find_by [[find_by]]
Prefer find_by over where.take and find_by_attribute when you need to retrieve a single record by one or more attributes and return nil when the record is not found.
User.where(email: email).take User.where(first_name: 'Bruce', last_name: 'Wayne').take
User.find_by_email(email) User.find_by_first_name_and_last_name('Bruce', 'Wayne')
=== Hash conditions [[where-not]] [[hash-conditions]]
Prefer passing conditions to where and where.not as a hash over using fragments of SQL.
User.where("name = ?", name)
User.where(name: name)
User.where("id != ?", id)
=== Finding missing relationship records [[finding-missing-relationship-records]]
If you're using Rails 6.1 or higher, use https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods/WhereChain.html#method-i-missing[where.missing] to find missing relationship records.
Post.left_joins(:author).where(authors: { id: nil })
=== Order by id [[order-by-id]]
Don't use the id column for ordering.
The sequence of ids is not guaranteed to be in any particular order, despite often (incidentally) being chronological.
Use a timestamp column to order chronologically.
As a bonus the intent is clearer.
scope :chronological, -> { order(id: :asc) }
=== pluck
Use https://api.rubyonrails.org/classes/ActiveRecord/Calculations.html#method-i-pluck[pluck] to select a single value from multiple records.
User.all.map(&:name)
User.all.map { |user| user[:name] }
=== pick
Use https://api.rubyonrails.org/classes/ActiveRecord/Calculations.html#method-i-pick[pick] to select a single value from a single record.
User.pluck(:name).first
User.first.name
=== ids [[ids]]
Prefer ids over pluck(:id).
User.pluck(:id)
=== Squished Heredocs [[squished-heredocs]]
When specifying an explicit query in a method such as find_by_sql, use heredocs with squish.
This allows you to legibly format the SQL with line breaks and indentations, while supporting syntax highlighting in many tools (including GitHub, Atom, and RubyMine).
User.find_by_sql(<<-SQL.squish) SELECT users.id, accounts.plan FROM users INNER JOIN accounts ON accounts.user_id = users.id
https://api.rubyonrails.org/classes/String.html#method-i-squish[`String#squish`] removes the indentation and newline characters so that your server log shows a fluid string of SQL rather than something like this:
=== size over count or length [[size-over-count-or-length]]
When querying Active Record collections, prefer size (selects between count/length behavior based on whether collection is already loaded) or length (always loads the whole collection and counts the array elements) over count (always does a database query for the count).
User.count
User.all.size
=== Where with Ranges [[where-ranges]]
Use ranges instead of defining comparative conditions using a template for scalar values.
User.where("created_at >= ?", 30.days.ago).where("created_at <= ?", 7.days.ago) User.where("created_at >= ? AND created_at <= ?", 30.days.ago, 7.days.ago) User.where("created_at >= :start AND created_at <= :end", start: 30.days.ago, end: 7.days.ago)
User.where(created_at: 30.days.ago..7.days.ago)
User.where("created_at >= ?", 7.days.ago)
User.where(created_at: 7.days.ago..)
User.where(created_at: 7.days.ago..) # produces >= User.where(created_at: 7.days.ago...) # also produces >= User.where(created_at: ..7.days.ago) # inclusive: produces <= User.where(created_at: ...7.days.ago) # exclusive: produces <
NOTE: Rails 6.0 or later is required for endless range Ruby 2.6 syntax, and Rails 6.0.3 for beginless range Ruby 2.7 syntax.
=== where.not with multiple attributes
Avoid passing multiple attributes to where.not. Rails logic in this case has changed in Rails 6.1 and
will now yield results matching either of those conditions,
e.g. where.not(status: 'active', plan: 'basic') would return records with active status when the plan is business.
User.where.not(status: 'active', plan: 'basic')
=== Redundant all [[redundant-all]]
Using all as a receiver is redundant. The result won't change without all, so it should be removed.
User.all.find(id) User.all.order(:created_at) users.all.where(id: ids) user.articles.all.order(:created_at)
NOTE: When the receiver for all is an association, there are methods whose behavior changes by omitting all.
The following methods behave differently without all:
delete - https://api.rubyonrails.org/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-delete[with all] / https://api.rubyonrails.org/classes/ActiveRecord/Associations/CollectionProxy.html#method-i-delete[without all]delete_all - https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-delete_all[with all] / https://api.rubyonrails.org/classes/ActiveRecord/Associations/CollectionProxy.html#method-i-delete_all[without all]destroy - https://api.rubyonrails.org/classes/ActiveRecord/Persistence/ClassMethods.html#method-i-destroy[with all] / https://api.rubyonrails.org/classes/ActiveRecord/Associations/CollectionProxy.html#method-i-destroy[without all]destroy_all - https://api.rubyonrails.org/classes/ActiveRecord/Relation.html#method-i-destroy_all[with all] / https://api.rubyonrails.org/classes/ActiveRecord/Associations/CollectionProxy.html#method-i-destroy_all[without all]So, when considering removing all from the receiver of these methods, it is recommended to refer to the documentation to understand how the behavior changes.
== Migrations
=== Schema Version [[schema-version]]
Keep the schema.rb (or structure.sql) under version control.
=== DB Schema Load [[db-schema-load]]
Use rake db:schema:load instead of rake db:migrate to initialize an empty database.
=== Default Migration Values [[default-migration-values]]
Enforce default values in the migrations themselves instead of in the application layer.
class Product < ApplicationRecord def amount self[:amount] || 0 end end
While enforcing table defaults only in Rails is suggested by many Rails developers, it's an extremely brittle approach that leaves your data vulnerable to many application bugs. And you'll have to consider the fact that most non-trivial apps share a database with other applications, so imposing data integrity from the Rails app is impossible.
=== 3-state Boolean [[three-state-boolean]]
With SQL databases, if a boolean column is not given a default value, it will have three possible values: true, false and NULL.
Boolean operators https://en.wikipedia.org/wiki/Three-valued_logic[work in unexpected ways] with NULL.
For example in SQL queries, true AND NULL is NULL (not false), true AND NULL OR false is NULL (not false). This can make SQL queries return unexpected results.
To avoid such situations, boolean columns should always have a default value and a NOT NULL constraint.
add_column :users, :active, :boolean
false or true) and with restricted NULL=== Foreign Key Constraints [[foreign-key-constraints]]
Enforce foreign-key constraints. As of Rails 4.2, Active Record supports foreign key constraints natively.
create_table :comment do |t| t.references :article t.belongs_to :user t.integer :category_id end
=== Change vs Up/Down [[change-vs-up-down]]
When writing constructive migrations (adding tables or columns), use the change method instead of up and down methods.
class AddNameToPeople < ActiveRecord::Migration def up add_column :people, :name, :string end
def down remove_column :people, :name end end
=== Define Model Class Migrations [[define-model-class-migrations]]
If you have to use models in migrations, make sure you define them so that you don't end up with broken migrations in the future.
class ModifyDefaultStatusForProducts < ActiveRecord::Migration def change old_status = 'pending_manual_approval' new_status = 'pending_approval'
reversible do |dir|
dir.up do
Product.where(status: old_status).update_all(status: new_status)
change_column :products, :status, :string, default: new_status
end
dir.down do
Product.where(status: new_status).update_all(status: old_status)
change_column :products, :status, :string, default: old_status
end
endend end
table_name in a custom named class to make sure that you run on theProduct class and change the table_name,class MigrationProduct < ActiveRecord::Base self.table_name = :products end
class ModifyDefaultStatusForProducts < ActiveRecord::Migration def change old_status = 'pending_manual_approval' new_status = 'pending_approval'
reversible do |dir|
dir.up do
MigrationProduct.where(status: old_status).update_all(status: new_status)
change_column :products, :status, :string, default: new_status
end
dir.down do
MigrationProduct.where(status: new_status).update_all(status: old_status)
change_column :products, :status, :string, default: old_status
end
end=== Meaningful Foreign Key Naming [[meaningful-foreign-key-naming]]
Name your foreign keys explicitly instead of relying on Rails auto-generated FK names. (https://guides.rubyonrails.org/active_record_migrations.html#foreign-keys)
class AddFkArticlesToAuthors < ActiveRecord::Migration def change add_foreign_key :articles, :authors end end
=== Reversible Migration [[reversible-migration]]
Don't use non-reversible migration commands in the change method.
Reversible migration commands are listed below.
https://api.rubyonrails.org/classes/ActiveRecord/Migration/CommandRecorder.html[ActiveRecord::Migration::CommandRecorder]
class DropUsers < ActiveRecord::Migration def change drop_table :users end end
class DropUsers < ActiveRecord::Migration def up drop_table :users end
def down create_table :users do |t| t.string :name end end end
== Views
=== No Direct Model View [[no-direct-model-view]]
Never call the model layer directly from a view.
=== No Complex View Formatting [[no-complex-view-formatting]]
Avoid complex formatting in the views. A view helper is useful for simple cases, but if it's more complex then consider using a decorator or presenter.
=== Partials [[partials]]
Mitigate code duplication by using partial templates and layouts.
=== No Instance Variables in Partials [[no-instance-variables-in-partials]]
Avoid using instance variables in partials, pass a local variable to render instead.
The partial may be used in a different controller or action, where the variable can have a different name or even be absent.
In these cases, an undefined instance variable will not raise an exception whereas a local variable will.
<%= render 'course_description' %>
<%= @course.description %>
<%= render 'course_description', course: @course %>
== Internationalization
=== Locale Texts [[locale-texts]]
No strings or other locale specific settings should be used in the views, models and controllers.
These texts should be moved to the locale files in the config/locales directory.
=== Translated Labels [[translated-labels]]
When the labels of an Active Record model need to be translated, use the activerecord scope:
Then User.model_name.human will return "Member" and User.human_attribute_name("name") will return "Full name".
These translations of the attributes will be used as labels in the views.
=== Organize Locale Files [[organize-locale-files]]
Separate the texts used in the views from translations of Active Record attributes.
Place the locale files for the models in a folder locales/models and the texts used in the views in folder locales/views.
When organization of the locale files is done with additional directories, these directories must be described in the application.rb file in order to be loaded.
=== Shared Localization [[shared-localization]]
Place the shared localization options, such as date or currency formats, in files under the root of the locales directory.
=== Short I18n [[short-i18n]]
Use the short form of the I18n methods: I18n.t instead of I18n.translate and I18n.l instead of I18n.localize.
=== Lazy Lookup [[lazy-lookup]]
Use "lazy" lookup for locale entries from views and controllers. Let's say we have the following structure:
The value for users.show.title can be looked up in the template app/views/users/show.html.haml like this:
= t 'users.show.title'
=== Dot-separated Keys [[dot-separated-keys]]
Use dot-separated locale keys instead of specifying the :scope option with an array or a single symbol.
Dot-separated notation is easier to read and trace the hierarchy.
I18n.t :record_invalid, scope: [:activerecord, :errors, :messages]
I18n.t :record_invalid, scope: 'activerecord.errors.messages' I18n.t 'activerecord.errors.messages.record_invalid'
I18n.t :title, scope: :invitation
=== I18n Guides [[i18n-guides]]
More detailed information about the Rails I18n can be found in the https://guides.rubyonrails.org/i18n.html[Rails Guides]
== Assets
Use the https://guides.rubyonrails.org/asset_pipeline.html[asset pipeline] to leverage organization within your application.
=== Reserve app/assets [[reserve-app-assets]]
Reserve app/assets for custom stylesheets, javascripts, or images.
=== lib/assets [[lib-assets]]
Use lib/assets for your own libraries that don't really fit into the scope of the application.
=== vendor/assets [[vendor-assets]]
Third party code such as https://jquery.com/[jQuery] or https://twitter.github.com/bootstrap/[bootstrap] should be placed in vendor/assets.
=== gem/assets [[gem-assets]]
When possible, use gemified versions of assets (e.g. https://github.com/rails/jquery-rails[jquery-rails], https://github.com/joliss/jquery-ui-rails[jquery-ui-rails], https://github.com/thomas-mcdonald/bootstrap-sass[bootstrap-sass], https://github.com/zurb/foundation[zurb-foundation]).
== Mailers
=== Mailer Name [[mailer-name]]
Name the mailers SomethingMailer.
Without the Mailer suffix it isn't immediately apparent what's a mailer and which views are related to the mailer.
=== HTML Plain Email [[html-plain-email]]
Provide both HTML and plain-text view templates.
=== Enable Delivery Errors [[enable-delivery-errors]]
Enable errors raised on failed mail delivery in your development environment. The errors are disabled by default.
=== Local SMTP [[local-smtp]]
Use a local SMTP server like https://github.com/sj26/mailcatcher[Mailcatcher] in development environment.
config.action_mailer.smtp_settings = { address: 'localhost', port: 1025,
=== Default Hostname [[default-hostname]]
Provide default settings for the host name.
config.action_mailer.default_url_options = { host: "#{local_ip}:3000" }
config.action_mailer.default_url_options = { host: 'your_site.com' }
=== Email Addresses [[email-addresses]]
Format the from and to addresses properly. Use the following format:
If you're using Rails 6.1 or higher, you can use the email_address_with_name method:
=== Delivery Method Test [[delivery-method-test]]
Make sure that the e-mail delivery method for your test environment is set to test:
=== Delivery Method SMTP [[delivery-method-smtp]]
The delivery method for development and production should be smtp:
=== Inline Email Styles [[inline-email-styles]]
When sending html emails all styles should be inline, as some mail clients have problems with external styles. This however makes them harder to maintain and leads to code duplication. There are two similar gems that transform the styles and put them in the corresponding html tags: https://github.com/fphilipe/premailer-rails[premailer-rails] and https://github.com/Mange/roadie[roadie].
=== Background Email [[background-email]]
Sending emails while generating page response should be avoided. It causes delays in loading of the page and request can timeout if multiple email are sent. To overcome this emails can be sent in background process with the help of https://github.com/mperham/sidekiq[sidekiq] gem.
== Active Support Core Extensions
=== try! [[try-bang]]
Prefer Ruby 2.3's safe navigation operator &. over ActiveSupport#try!.
obj.try! :fly
=== Active Support Aliases [[active_support_aliases]]
Prefer Ruby's Standard Library methods over ActiveSupport aliases.
'the day'.starts_with? 'th' 'the day'.ends_with? 'ay'
=== Active Support Extensions [[active_support_extensions]]
Prefer Ruby's Standard Library over uncommon Active Support extensions.
(1..50).to_a.forty_two 1.in? [1, 2] 'day'.in? 'the day'
=== inquiry [[inquiry]]
Prefer Ruby's comparison operators over Active Support's Array#inquiry, and String#inquiry.
ruby = 'two'.inquiry ruby.two?
ruby = 'two' ruby == 'two'
pets = %w(cat dog).inquiry pets.gopher?
=== exclude? [[exclude]]
Prefer Active Support's exclude? over Ruby's negated include?.
!array.include?(2) !hash.include?(:key) !string.include?('substring')
=== Prefer using squiggly heredoc over strip_heredoc [[prefer-squiggly-heredoc]]
If you're using Ruby 2.3 or higher, prefer squiggly heredoc (<<~) over Active Support's strip_heredoc.
<<EOS.strip_heredoc some text EOS
<<-EOS.strip_heredoc some text EOS
=== Prefer to_fs for Formatted Strings [[prefer-to-fs]]
If you're using Rails 7.0 or higher, prefer to_fs over to_formatted_s. to_formatted_s is just too cumbersome for a method used that frequently.
time.to_formatted_s(:db) date.to_formatted_s(:db) datetime.to_formatted_s(:db) 42.to_formatted_s(:human)
== Time
=== Time Zone Config [[tz-config]]
Configure your timezone accordingly in application.rb.
config.time_zone = 'Eastern European Time'
=== Time.parse [[time-parse]]
Don't use Time.parse.
Time.parse('2015-03-02 19:05:37') # => Will assume time string given is in the system's time zone.
=== to_time [[to-time]]
Don't use https://api.rubyonrails.org/classes/String.html#method-i-to_time[`String#to_time`]
'2015-03-02 19:05:37'.to_time
=== Time.now [[time-now]]
Don't use Time.now.
Time.now # => Returns system time and ignores your configured time zone.
=== Prefer all_(day|week|month|quarter|year) over range of date/time [[date-time-range]]
Prefer all_(day|week|month|quarter|year) over beginning_of_(day|week|month|quarter|year)..end_of_(day|week|month|quarter|year)
to get the range of date/time.
date.beginning_of_day..date.end_of_day date.beginning_of_week..date.end_of_week date.beginning_of_month..date.end_of_month date.beginning_of_quarter..date.end_of_quarter date.beginning_of_year..date.end_of_year
== Duration
=== Duration Application
If used without a parameter, prefer from_now and ago instead of since, after, until or before.
5.hours.since 5.hours.after 5.hours.before 5.hours.until
If used with a parameter, prefer since, after, until or before instead of from_now and ago.
2.days.from_now(yesterday) 2.days.ago(yesterday)
Avoid using negative numbers for the duration subject. Always prefer using a qualifier that allows using positive literal numbers.
-5.hours.from_now -5.hours.ago
=== Duration Arithmetic
Use Duration methods instead of adding and subtracting with the current time.
Time.current - 1.minute Time.zone.now + 2.days
== Bundler
=== Dev/Test Gems [[dev-test-gems]]
Put gems used only for development or testing in the appropriate group in the Gemfile.
=== Only Good Gems [[only-good-gems]]
Use only established gems in your projects. If you're contemplating on including some little-known gem you should do a careful review of its source code first.
=== Gemfile.lock [[gemfile-lock]]
Do not remove the Gemfile.lock from version control.
This is not some randomly generated file - it makes sure that all of your team members get the same gem versions when they do a bundle install.
== Testing
=== Integration Testing
Prefer integration style controller tests over functional style controller tests, https://api.rubyonrails.org/v7.0.0/classes/ActionController/TestCase.html[as recommended in the Rails documentation].
class MyControllerTest < ActionController::TestCase end
=== freeze_time [[freeze-time]]
Prefer https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html#method-i-freeze_time[ActiveSupport::Testing::TimeHelpers#freeze_time] over https://api.rubyonrails.org/classes/ActiveSupport/Testing/TimeHelpers.html#method-i-travel_to[ActiveSupport::Testing::TimeHelpers#travel_to] with an argument of the current time.
travel_to(Time.now) travel_to(DateTime.now) travel_to(Time.current) travel_to(Time.zone.now) travel_to(Time.now.in_time_zone) travel_to(Time.current.to_time)
== Managing Processes
=== Foreman [[foreman]]
If your projects depends on various external processes use https://github.com/ddollar/foreman[foreman] to manage them.
== Further Reading
There are a few excellent resources on Rails style, that you should consider if you have time to spare:
== Contributing
Nothing written in this guide is set in stone. It's my desire to work together with everyone interested in Rails coding style, so that we could ultimately create a resource that will be beneficial to the entire Ruby community.
Feel free to open tickets or send pull requests with improvements. Thanks in advance for your help!
You can also support the project (and RuboCop) with financial contributions via https://www.patreon.com/bbatsov[Patreon].
=== How to Contribute?
It's easy, just follow the contribution guidelines below:
== License
image:https://i.creativecommons.org/l/by/3.0/88x31.png[Creative Commons License] This work is licensed under a https://creativecommons.org/licenses/by/3.0/deed.en_US[Creative Commons Attribution 3.0 Unported License]
== Spread the Word
A community-driven style guide is of little use to a community that doesn't know about its existence. Tweet about the guide, share it with your friends and colleagues. Every comment, suggestion or opinion we get makes the guide just a little bit better. And we want to have the best possible guide, don't we?
Cheers, + https://twitter.com/bbatsov[Bozhidar]