diff options
Diffstat (limited to 'doc/development/backend/ruby_style_guide.md')
| -rw-r--r-- | doc/development/backend/ruby_style_guide.md | 87 |
1 files changed, 38 insertions, 49 deletions
diff --git a/doc/development/backend/ruby_style_guide.md b/doc/development/backend/ruby_style_guide.md index 9b5a68e4292..1a1c0db49f7 100644 --- a/doc/development/backend/ruby_style_guide.md +++ b/doc/development/backend/ruby_style_guide.md @@ -7,31 +7,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Ruby style guide -This is a GitLab-specific style guide for Ruby code. +This is a GitLab-specific style guide for Ruby code. Everything documented in this page can be [reopened for discussion](https://about.gitlab.com/handbook/values/#disagree-commit-and-disagree). -Generally, if a style is not covered by [existing RuboCop rules or style guides](../contributing/style_guides.md#ruby-rails-rspec), it shouldn't be a blocker. -Before adding a new cop to enforce a given style, make sure to discuss it with your team. -When the style is approved by a backend EM or by a BE staff eng, add a new section to this page to -document the new rule. For every new guideline, add it in a new section and link the discussion from the section's -[version history note](../documentation/versions.md#add-a-version-history-item) -to provide context and serve as a reference. +We use [RuboCop](../rubocop_development_guide.md) to enforce Ruby style guide rules. -See also [guidelines for reusing abstractions](../reusing_abstractions.md). +Where a RuboCop rule is absent, refer to the following style guides as general guidelines to write idiomatic Ruby: -Everything listed here can be [reopened for discussion](https://about.gitlab.com/handbook/values/#disagree-commit-and-disagree). +- [Ruby Style Guide](https://github.com/rubocop/ruby-style-guide). +- [Rails Style Guide](https://github.com/rubocop/rails-style-guide). +- [RSpec Style Guide](https://github.com/rubocop/rspec-style-guide). -## String literals quoting +Generally, if a style is not covered by existing RuboCop rules or the above style guides, it shouldn't be a blocker. -Due to the sheer amount of work to rectify, we do not care whether string -literals are single, or double quoted. +Some styles we have decided [no one should not have a strong opinion on](#styles-we-have-no-opinion-on). -Previous discussions include: +See also: -- <https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44234> -- <https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36076> -- <https://gitlab.com/gitlab-org/gitlab/-/issues/198046> +- [Guidelines for reusing abstractions](../reusing_abstractions.md). +- [Test-specific style guides and best practices](../testing_guide/index.md). + +## Styles we have no rule for -## Instance variable access using `attr_reader` +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](../documentation/versions.md#add-a-version-history-item) to provide context and serve as a reference. + +### Instance variable access using `attr_reader` > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52351) in GitLab 14.1. @@ -84,11 +85,11 @@ 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. -## Newlines style guide +### Newlines style guide -This style guide recommends best practices for newlines in Ruby code. +In addition to the RuboCops `Layout/EmptyLinesAroundMethodBody` and `Cop/LineBreakAroundConditionalBlock` that enforce some newline styles, we have the following guidelines that are not backed by RuboCop. -### Rule: separate code with newlines only to group together related logic +#### Rule: separate code with newlines only to group together related logic ```ruby # bad @@ -111,9 +112,7 @@ def method end ``` -### Rule: separate code and block with newlines - -#### Newline before block +#### Rule: newline before block ```ruby # bad @@ -136,35 +135,11 @@ def method end ``` -### Rule: Newline after block - -```ruby -# bad -def method - if issue.save - issue.send_email - end - render json: issue -end -``` - -```ruby -# good -def method - if issue.save - issue.send_email - end - - render json: issue -end -``` - -#### Exception: no need for newline when code block starts or ends right inside another code block +##### Exception: no need for a newline when code block starts or ends right inside another code block ```ruby # bad def method - if issue if issue.valid? @@ -172,7 +147,6 @@ def method end end - end ``` @@ -186,3 +160,18 @@ def method end end ``` + +## Styles we have no opinion on + +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. + +### Quoting string literals + +Due to the sheer amount of work to rectify, we do not care whether string +literals are single or double-quoted. + +Previous discussions include: + +- <https://gitlab.com/gitlab-org/gitlab-foss/-/issues/44234> +- <https://gitlab.com/gitlab-org/gitlab-foss/-/issues/36076> +- <https://gitlab.com/gitlab-org/gitlab/-/issues/198046> |