- Styles we have no rule for
- Avoid ActiveRecord callbacks
- Why callbacks should be avoided
- Styles we have no opinion on
This is a GitLab-specific style guide for Ruby code. Everything documented in this page can be reopened for discussion.
We use RuboCop to enforce Ruby style guide rules.
Where a RuboCop rule is absent, refer to the following style guides as general guidelines to write idiomatic Ruby:
Generally, if a style is not covered by existing RuboCop rules or the above style guides, it shouldn’t be a blocker.
Some styles we have decided no one should not have a strong opinion on.
These styles are not backed by a RuboCop rule.
For every style added to this section, link the discussion from the section’s version history note to provide context and serve as a reference.
Introduced in GitLab 14.1.
Instance variables can be accessed in a variety of ways in a class:
# public class Foo attr_reader :my_var def initialize(my_var) @my_var = my_var end def do_stuff puts my_var end end # private class Foo def initialize(my_var) @my_var = my_var end private attr_reader :my_var def do_stuff puts my_var end end # direct class Foo def initialize(my_var) @my_var = my_var end private def do_stuff puts @my_var end end
Public attributes should only be used if they are accessed outside of the class. There is not a strong opinion on what strategy is used when attributes are only accessed internally, as long as there is consistency in related code.
In addition to the RuboCops
Cop/LineBreakAroundConditionalBlock that enforce some newline styles, we have the following guidelines that are not backed by RuboCop.
# bad def method issue = Issue.new issue.save render json: issue end
# good def method issue = Issue.new issue.save render json: issue end
# bad def method issue = Issue.new if issue.save render json: issue end end
# good def method issue = Issue.new if issue.save render json: issue end end
# bad def method if issue if issue.valid? issue.save end end end
# good def method if issue if issue.valid? issue.save end end end
ActiveRecord callbacks allow you to “trigger logic before or after an alteration of an object’s state.”
Use callbacks when no superior alternative exists, but employ them only if you thoroughly understand the reasons for doing so.
When adding new lifecycle events for ActiveRecord objects, it is preferable to add the logic to a service class instead of a callback.
In general, callbacks should be avoided because:
- Callbacks are hard to reason about because invocation order is not obvious and they break code narrative.
- Callbacks are harder to locate and navigate because they rely on reflection to trigger rather than being ordinary method calls.
- Callbacks make it difficult to apply changes selectively to an object’s state because changes always trigger the entire callback chain.
- Callbacks trap logic in the ActiveRecord class. This tight coupling encourages fat models that contain too much business logic, which could instead live in service objects that are more reusable, composable, and are easier to test.
- Illegal state transitions of an object can be better enforced through attribute validations.
- Heavy use of callbacks affects factory creation speed. With some classes having hundreds of callbacks, creating an instance of that object for an automated test can be a very slow operation, resulting in slow specs.
Some of these examples are discussed in this video from thoughtbot.
The GitLab codebase relies heavily on callbacks and it is hard to refactor them once added due to invisible dependencies. As a result, this guideline does not call for removing all existing callbacks.
Callbacks can be used in special cases. Some examples of cases where adding a callback makes sense:
- A dependency uses callbacks and we would like to override the callback behavior.
- Incrementing cache counts.
- Data normalization that only relates to data on the current model.
There is a project with the following basic data model:
class Project has_one :repository end class Repository belongs_to :project end
Say we want to create a repository after a project is created and use the project name as the repository name. A developer familiar with Rails might immediately think: sounds like a job for an ActiveRecord callback! And add this code:
class Project has_one :repository after_initialize :create_random_name after_create :create_repository def create_random_name SecureRandom.alphanumeric end def create_repository Repository.create!(project: self) end end class Repository after_initialize :set_name def set_name name = project.name end end class ProjectsController def create Project.create! # also creates a repository and names it end end
While this seems pretty harmless for a baby Rails app, adding this type of logic via callbacks has many downsides once your Rails app becomes large and complex (all of which are listed in this documentation). Instead, we can add this logic to a service class:
class Project has_one :repository end class Repository belongs_to :project end class ProjectCreator def self.execute ApplicationRecord.transaction do name = SecureRandom.alphanumeric project = Project.create!(name: name) Repository.create!(project: project, name: name) end end end class ProjectsController def create ProjectCreator.execute end end
With an application this simple, it can be hard to see the benefits of the second approach. But we already some benefits:
- Can test
Repositorycreation logic separate from
Projectcreation logic. Code no longer violates law of demeter (
Repositoryclass doesn’t need to know
- Clarity of invocation order.
- Open to change: if we decide there are some scenarios where we do not want a
repository created for a project, we can create a new service class rather
than needing to refactor to
- Each instance of a
Projectfactory does not create a second (
If a RuboCop rule is proposed and we choose not to add it, we should document that decision in this guide so it is more discoverable and link the relevant discussion as a reference.
Due to the sheer amount of work to rectify, we do not care whether string literals are single or double-quoted.
Previous discussions include:
Now that we’ve upgraded to Ruby 3, we have more options available to enforce type safety.
Some of these options are supported as part of the Ruby syntax and do not require the use of specific type safety tools like Sorbet or RBS. However, we might consider these tools in the future as well.
For more information, see Type safety in the
remote_development domain README.
Functional programming patterns, especially in domain logic, can often result in more readable, maintainable, and bug-resistant code while still using idiomatic and familiar Ruby patterns.
However, functional programming patterns should be used carefully because some patterns would cause confusion and should be avoided even if they’re directly supported by Ruby. The
curry method is a likely example.
For more information, see: