lifen-ruby-style 0.2.1 → 1.0.0

data/style_guide.md

@@ -0,0 +1,673 @@
+# The Lifen Ruby Style Guide
+
+In this guide, we present the Lifen guidelines, the most important rules and the specific ones (i.e. rules with custom config, different from [RuboCop default ones](https://github.com/rubocop-hq/ruby-style-guide)).
+
+## General
+
+- Make all lines of your methods operate on the same level of abstraction. ([Single Level of Abstraction Principle](https://medium.com/@yukas/single-level-of-abstraction-1e2bb6a645d7))
+- Do not mutate arguments unless that is the purpose of the method.
+- Do not mess around in / monkeypatch core classes when writing libraries.
+- Keep the code simple.
+- Avoid needless metaprogramming.
+
+(based on [Shopify's ruby style guide](https://shopify.github.io/ruby-style-guide/))
+
+## Not-RuboCop rules
+
+- Prefer `public_send` over `send` so as not to circumvent private/protected visibility.
+- Prefer using [ActiveRecord Bang (!) Methods](https://riptutorial.com/ruby-on-rails/example/9285/activerecord-bang-----methods), such as `#save!`, `#update!`, `.create!`. Careful, you must not use a Bang Method and then rescue an exception. You should prevent the app to get invalid inputs beforehand.
+- Always use `destroy!` or `destroy`. Never use `delete`, unless you know exactly why. Basically `destroy` runs any callbacks on the model while `delete` doesn't. More [info](https://api.rubyonrails.org/classes/ActiveRecord/Persistence.html#method-i-delete).
+- Prefer `Time` over `DateTime` since it supports proper time zones instead of UTC offsets. [More info](https://gist.github.com/pixeltrix/e2298822dd89d854444b).
+
+## RuboCop rules
+
+**All RuboCop rules are enforced by the linter: you don't have to memorize them all. This section is for documentation purposes only.**
+
+### Custom rules
+
+All the RuboCop rules overrided by Lifen are detailed below:
+
+<details><summary>Layout</summary>
+
+#### ArgumentAlignment
+
+```ruby
+# bad
+foo :bar,
+    :baz
+
+# good
+foo :bar,
+  :baz
+```
+
+#### CaseIndentation
+
+```ruby
+# bad
+case n
+  when 0
+    x * 2
+  else
+    y / 3
+end
+
+# good
+case n
+when 0
+  x * 2
+else
+  y / 3
+end
+
+# bad
+a = case n
+    when 0
+      x * 2
+    else
+      y / 3
+end
+
+# good
+a = case n
+when 0
+  x * 2
+else
+  y / 3
+end
+```
+
+#### EmptyLinesAroundClassBody
+
+```ruby
+# bad
+class Foo
+  def bar
+    # ...
+  end
+end
+
+# good
+class Foo
+
+  def bar
+    # ...
+  end
+
+end
+```
+
+#### EmptyLinesAroundModuleBody
+
+```ruby
+# bad
+module Foo
+  def bar
+    # ...
+  end
+end
+
+# good
+module Foo
+
+  def bar
+    # ...
+  end
+
+end
+```
+
+#### EndAlignment
+
+```ruby
+# bad
+variable = if true
+    end
+
+# good
+variable = if true
+end
+
+variable =
+  if true
+  end
+```
+
+#### FirstArgumentIndentation
+
+```ruby
+# bad
+some_method(
+first_param,
+second_param)
+# good
+some_method(
+  first_param,
+  second_param
+)
+
+# bad
+foo = some_method(
+first_param,
+second_param)
+# good
+foo = some_method(
+  first_param,
+  second_param
+)
+
+# bad
+foo = some_method(nested_call(
+nested_first_param),
+second_param)
+# good
+foo = some_method(nested_call(
+  nested_first_param
+),
+  second_param)
+
+# bad
+foo = some_method(
+nested_call(
+nested_first_param),
+second_param)
+# good
+foo = some_method(
+  nested_call(
+    nested_first_param
+  ),
+  second_param
+)
+
+# bad
+some_method nested_call(
+nested_first_param),
+second_param
+# good
+some_method nested_call(
+  nested_first_param
+),
+  second_param
+```
+
+#### FirstArrayElementIndentation
+
+```ruby
+#bad
+# consistent
+array = [
+  :value
+]
+but_in_a_method_call([
+                      :its_like_this
+])
+
+#good
+array = [
+  :value
+]
+and_in_a_method_call([
+  :no_difference
+])
+```
+
+#### FirstHashElementIndentation
+
+```ruby
+# bad
+hash = {
+  key: :value
+}
+but_in_a_method_call(
+                      its_like: :this
+                    )
+
+# good
+hash = {
+  key: :value
+}
+and_in_a_method_call(
+  no: :difference
+)
+```
+
+#### IndentationConsistency
+
+```ruby
+# bad
+class A
+
+  def test
+    puts 'hello'
+    puts 'world'
+  end
+
+  private
+
+  def bar
+    puts 'world'
+  end
+
+end
+
+# good
+class A
+
+  def test
+    puts 'hello'
+    puts 'world'
+  end
+
+  private
+
+    def bar
+      puts 'hello'
+    end
+
+end
+```
+
+#### LineLength
+
+Maximum of 120 characters
+
+#### MultilineMethodCallIndentation
+
+```ruby
+# bad
+while myvariable
+.b
+  # do something
+end
+
+# good
+while myvariables
+    .b
+  # do something
+end
+
+# bad
+def my_method
+  my_variable
+  .method_1
+  .method_2
+end
+
+# good
+def my_method
+  my_variable
+    .method_1
+    .method_2
+end
+```
+
+#### ParameterAlignment
+
+```ruby
+# bad
+def foo(bar,
+        baz)
+  puts bar + baz
+end
+
+# good
+def foo(bar,
+  baz)
+  puts bar + baz
+end
+
+# bad
+def foo(
+  bar,
+    baz)
+  puts bar + baz
+end
+
+# good
+def foo(
+  bar,
+  baz
+)
+  puts bar + baz
+end
+```
+
+</details>
+
+<details><summary>Linting</summary>
+
+#### RescueException
+
+```yaml
+Enabled: false // does not check for rescue blocks targeting the Exception class.
+```
+
+```ruby
+# NOT bad
+begin
+  do_something
+rescue Exception
+  handle_exception
+end
+
+# good
+begin
+  do_something
+rescue ArgumentError
+  handle_exception
+end
+```
+
+</details>
+
+<details><summary>Metrics</summary>
+
+#### AbcSize
+
+```yaml
+Enabled: false // does not check ABC size of methods
+```
+
+#### BlockLength
+
+```yaml
+Enabled: false // does not check if the length of a block exceeds some maximum value.
+```
+
+#### ClassLength
+
+```yaml
+Max: 250 // checks if the length of a class exceeds 250
+```
+
+#### CyclomaticComplexity
+
+```yaml
+Enabled: false // does not check the cyclomatic complexity
+```
+
+#### MethodLength
+
+```yaml
+Max: 40 // checks if the length of a method exceeds 40
+```
+
+#### ModuleLength
+
+```yaml
+Max: 250 // checks if the length of a module exceeds 250
+```
+
+#### PerceivedComplexity
+
+```yaml
+Enabled: false // does not check the perceived complexity
+```
+
+</details>
+
+<details><summary>Naming</summary>
+
+#### MemoizedInstanceVariableName
+
+```ruby
+# bad
+def foo
+  @something ||= calculate_expensive_thing
+end
+
+# bad
+def foo
+  @foo ||= calculate_expensive_thing
+end
+
+# good
+def foo
+  @_foo ||= calculate_expensive_thing
+end
+```
+
+</details>
+
+<details><summary>Style</summary>
+
+#### ClassAndModuleChildren
+
+```yaml
+Enabled: false // does not check the style of children definitions at classes and modules
+```
+
+```ruby
+# good
+class Foo
+  class Bar
+  end
+end
+# good
+class Foo::Bar
+end
+```
+
+#### Documentation
+
+```yaml
+Enabled: false // does not check for missing top-level documentation of classes and modules
+```
+
+```ruby
+# good
+class Person
+  # ...
+end
+
+# good
+# Description/Explanation of Person class
+class Person
+  # ...
+end
+```
+
+#### NumericLiterals
+
+```ruby
+# bad
+1000000
+1_00_000
+1_0000
+10_000_00 # typical representation of $10,000 in cents
+
+# good
+1_000_000
+1000
+```
+
+#### RegexpLiteral
+
+```ruby
+# bad
+snake_case = %r{^[\dA-Z_]+$}
+# good
+snake_case = /^[\dA-Z_]+$/
+
+# bad
+regex = %r{
+  foo
+  (bar)
+  (baz)
+}x
+# good
+regex = /
+  foo
+  (bar)
+  (baz)
+/x
+
+#bad
+x =~ %r{home/}
+# good
+x =~ /home\//
+```
+
+#### StructInheritance
+
+```yaml
+Enabled: false // does not check for inheritance from Struct.new.
+```
+
+```ruby
+# good
+class Person < Struct.new(:first_name, :last_name)
+
+  def age
+    42
+  end
+
+end
+
+# good
+Person = Struct.new(:first_name, :last_name) do
+  def age
+    42
+  end
+end
+```
+
+#### SymbolArray
+
+```ruby
+# bad
+%i[foo bar baz]
+
+# good
+[:foo, :bar, :baz]
+```
+
+#### WordArray
+
+```ruby
+# bad
+%w[foo bar baz]
+
+# good
+['foo', 'bar', 'baz']
+```
+
+</details>
+
+<details><summary>RSpec</summary>
+
+#### AnyInstance
+
+```yaml
+Enabled: false // instances can be stubbed globally.
+```
+
+```ruby
+# NOT bad
+describe MyClass do
+  before(:each) { allow_any_instance_of(MyClass).to receive(:foo) }
+end
+
+# good
+describe MyClass do
+  let(:my_instance) { instance_double(MyClass) }
+
+  before(:each) do
+    allow(MyClass).to receive(:new).and_return(my_instance)
+    allow(my_instance).to receive(:foo)
+  end
+end
+
+```
+
+#### DescribedClass
+
+```ruby
+# bad
+describe MyClass do
+  subject { described_class.do_something }
+end
+
+# good
+describe MyClass do
+  subject { MyClass.do_something }
+end
+```
+
+#### ExampleLength
+
+```yaml
+Enabled: false // does not check for long examples.
+```
+
+#### HookArgument
+
+```ruby
+# bad
+before(:example) do
+  # ...
+end
+
+# good
+before do
+  # ...
+end
+
+# good
+before(:each) do
+  # ...
+end
+```
+
+#### MultipleExpectations
+
+```yaml
+Enabled: false //  does not check if examples contain too many expect calls.
+```
+
+#### NestedGroups
+
+```yaml
+Max: 4 // checks if nested groups does not exceed 4 levels
+```
+
+#### NotToNot
+
+```ruby
+# bad
+it '...' do
+  expect(false).not_to be_true
+end
+
+# good
+it '...' do
+  expect(false).to_not be_true
+end
+```
+
+#### RepeatedDescription
+
+```yaml
+Enabled: false // example groups can have the same description string.
+```
+
+</details>
+
+### Default rules
+
+All other rules have the default configuration. They are detailed in the [RuboCop official documentation](https://docs.rubocop.org/en/stable/), in the [RSpec Extension official documentation](https://docs.rubocop.org/projects/rspec/en/stable/),in the [Performance Extension official documentation](https://docs.rubocop.org/projects/performance/en/stable/), and in the [Rails Extension official documentation](https://docs.rubocop.org/projects/rails/en/stable/).
+
+Below are documented the default RuboCop rules considered as particularly important. **They are also enforced by RuboCop!**
+
+#### Style/FrozenStringLiteralComment
+
+Freezing Strings feature improves apps performance by freezing Strings. So, Matz - Ruby’s creator - decided to make all String literals frozen (immutable) by default in Ruby 3.0.
+
+In order to have a transition path to this coming big change, we add a magic comment at the beginning of each file, which freezes strings by default:
+
+```ruby
+# frozen_string_literal: true
+class YourClass
+  # ...
+end
+```