<commit_before># Abstract

This document was created when I, as the Technical Lead of the company
in which I work for, was asked by the CTO to create some internal documents
describing good style and best practices for Ruby programming. I started off
by building upon
[this existing style guide](https://github.com/chneukirchen/styleguide),
since I concurred with most of the points in it. I hope it will be useful to
other people as well and I hope that I'll get a lot of feedback and
suggestions on how to improve the guide for the benefit of the entire Ruby
community.

## Formatting

* Use UTF-8 as the source file encoding.
* Use two space indent, no tabs. (Your editor/IDE should have a setting to
  help you with that.)
* Use Unix-style line endings. (Linux/OSX users are covered by default,
  Windows users have to be extra careful.)
    * If you're using Git you might want to do `$ git config --global
      core.autocrlf true` to protect your project from Windows line endings
      creeping into your project.
* Use spaces around operators, after commas, colons and semicolons, around {
  and before }.

    ```Ruby
    sum = 1 + 2
    a, b = 1, 2
    1 > 2 ? true : false; puts "Hi"
    [1, 2, 3].each { |e| puts e }
    ```

* No spaces after (, [ or before ], ).

    ```Ruby
    some(arg).other
    [1, 2, 3].length
    ```

* Indent **when** as deep as **case**. (As suggested in the Pickaxe.)

    ```Ruby
    case
    when song.name == "Misty"
      puts "Not again!" when song.duration > 120
      puts "Too long!" when Time.now.hour > 21
      puts "It's too late"
    else
      song.play
    end

    kind = case year
           when 1850..1889 then "Blues"
           when 1890..1909 then "Ragtime"
           when 1910..1929 then "New Orleans Jazz" when 1930..1939 then "Swing"
           when 1940..1950 then "Bebop"
           else "Jazz"
           end
    ```

* Use an empty line before the return value of a method (unless it
  only has one line), and an empty line between **def**s.

    ```Ruby
    def some_method
      do_something
      do_something_else

      result
    end

    def some_method
      result
    end
    ```
    
* Use RDoc and its conventions for API documentation.  Don't put an
  empty line between the comment block and the **def**.
* Use empty lines to break up a method into logical paragraphs.
* Keep lines fewer than 80 characters. (Emacs users should really have a look
  at whitespace-mode.)
* Avoid trailing whitespace. (Emacs users: Whitespace-mode again comes to the
  rescue.)

## Syntax

* Use **def** with parentheses when there are arguments. Omit the
  parentheses when the method doesn't accept any arguments.

     ```Ruby
     def some_method
       # body omitted
     end

     def some_method_with_arguments(arg1, arg2)
       # body omitted
     end
     ```

* Never use **for**, unless you know exactly why. Most of the time iterators
  should be used instead.

    ```Ruby        
    arr = [1, 2, 3]
        
    # bad
    for elem in arr do
      puts elem
    end

    # good
    arr.each { |elem| puts elem }
    ```
    
* Never use **then** for multiline **if/unless**.

    ```Ruby
    # bad
    if x.odd? then
      puts "odd"
    end

    # good
    if x.odd?
      puts "odd"
    end
    ```

* Favor **if/then/else** over the ternary operator. *if* is an
  expression in Ruby and the resulting code is arguably easier to
  read (albeit not as concise). Remember that _"Programs must be written for
  people to read, and only incidentally for machines to execute."_ (Abelson
  and Sussman)

    ```Ruby
    # good
    result = if some_condition then something else something_else end

    # not so good
    result = some_condition ? something : something_else
    ```

* Use **when x; ...** for one-line cases.
* Use **&&/||** for boolean expressions, **and/or** for control flow.  (Rule
  of thumb: If you have to use outer parentheses, you are using the
  wrong operators.)

    ```Ruby
    # boolean expression
    if some_condition && some_other_condition
      do_something
    end

    # control flow
    document.saved? or document.save!
    ```

* Avoid multiline ?: (the ternary operator), use **if/unless** instead.
* Favor modifier **if/unless** usage when you have a single-line
  body. Another good alternative is the usage of control flow **and/or**.

    ```Ruby
    # bad
    if some_condition
      do_something
    end

    # good
    do_something if some_condition

    # another good option
    some_condition and do_something
    ```

* Favor **unless** over **if** for negative conditions (or control
  flow **or**).
       
    ```Ruby
    # bad
    do_something if !some_condition

    # good
    do_something unless some_condition

    # another good option
    some_condition or do_something
    ```
    
* Suppress superfluous parentheses when calling methods, but keep them
  when calling "functions", i.e. when you use the return value in the
  same line.
  
    ```Ruby
    x = Math.sin(y)
    array.delete e
    ```
        
* Prefer {...} over do...end for single-line blocks.  Avoid using {...} for
  multi-line blocks.  Always use do...end for "control flow" and "method
  definitions" (e.g. in Rakefiles and certain DSLs.)  Avoid do...end when
  chaining.

* Avoid **return** where not required.

    ```Ruby
    # bad
    def some_method(some_arr)
      return some_arr.size
    end

    # good
    def some_method(some_arr)
      some_arr.size
    end
    ```

* Avoid line continuation (\\) where not required. In practice, avoid using
  line continuations at all.

    ```Ruby
    # bad
    result = 1 + \
    2

    # good (but still ugly as hell)
    result = 1 \
    \+ 2
    ```

* Using the return value of = is okay.

    ```Ruby
    if v = array.grep(/foo/) ...
    ```

* Use ||= freely.

    ```Ruby
    # set name to Bozhidar, only if it's nil or false
    name ||= "Bozhidar"
    ```

* Avoid using Perl-style global variables (like $0-9, $`, ...).

## Naming

* Use snake_case for methods and variables.
* Use CamelCase for classes and modules.  (Keep acronyms like HTTP,
  RFC, XML uppercase.)
* Use SCREAMING_SNAKE_CASE for other constants.
* The length of an identifier determines its scope.  Use one-letter variables
  for short block/method parameters, according to this scheme:

        a,b,c: any object
        d: directory names
        e: elements of an Enumerable
        ex: rescued exceptions
        f: files and file names
        i,j: indexes
        k: the key part of a hash entry
        m: methods
        o: any object
        r: return values of short methods
        s: strings
        v: any value
        v: the value part of a hash entry
        x,y,z: numbers

  And in general, the first letter of the class name if all objects are of
  that type.

* When using **inject** with short blocks, name the arguments **|a, e|**
  (accumulator, element).
* When defining binary operators, name the argument "other".

    ```Ruby
    def +(other)
      # body omitted
    end
    ```
    
* Prefer **map** over *collect*, **find** over *detect*, **find_all** over
  *select*, **size** over *length*. This is not a hard requirement; if the
  use of the alias enhances readability, it's ok to use it.

## Comments

* Write self documenting code and ignore the rest of this section.<commit_msg>Made argument naming convention consistent.<commit_after># Abstract

This document was created when I, as the Technical Lead of the company
in which I work for, was asked by the CTO to create some internal documents
describing good style and best practices for Ruby programming. I started off
by building upon
[this existing style guide](https://github.com/chneukirchen/styleguide),
since I concurred with most of the points in it. I hope it will be useful to
other people as well and I hope that I'll get a lot of feedback and
suggestions on how to improve the guide for the benefit of the entire Ruby
community.

## Formatting

* Use UTF-8 as the source file encoding.
* Use two space indent, no tabs. (Your editor/IDE should have a setting to
  help you with that.)
* Use Unix-style line endings. (Linux/OSX users are covered by default,
  Windows users have to be extra careful.)
    * If you're using Git you might want to do `$ git config --global
      core.autocrlf true` to protect your project from Windows line endings
      creeping into your project.
* Use spaces around operators, after commas, colons and semicolons, around {
  and before }.

    ```Ruby
    sum = 1 + 2
    a, b = 1, 2
    1 > 2 ? true : false; puts "Hi"
    [1, 2, 3].each { |e| puts e }
    ```

* No spaces after (, [ or before ], ).

    ```Ruby
    some(arg).other
    [1, 2, 3].length
    ```

* Indent **when** as deep as **case**. (As suggested in the Pickaxe.)

    ```Ruby
    case
    when song.name == "Misty"
      puts "Not again!" when song.duration > 120
      puts "Too long!" when Time.now.hour > 21
      puts "It's too late"
    else
      song.play
    end

    kind = case year
           when 1850..1889 then "Blues"
           when 1890..1909 then "Ragtime"
           when 1910..1929 then "New Orleans Jazz" when 1930..1939 then "Swing"
           when 1940..1950 then "Bebop"
           else "Jazz"
           end
    ```

* Use an empty line before the return value of a method (unless it
  only has one line), and an empty line between **def**s.

    ```Ruby
    def some_method
      do_something
      do_something_else

      result
    end

    def some_method
      result
    end
    ```
    
* Use RDoc and its conventions for API documentation.  Don't put an
  empty line between the comment block and the **def**.
* Use empty lines to break up a method into logical paragraphs.
* Keep lines fewer than 80 characters. (Emacs users should really have a look
  at whitespace-mode.)
* Avoid trailing whitespace. (Emacs users: Whitespace-mode again comes to the
  rescue.)

## Syntax

* Use **def** with parentheses when there are arguments. Omit the
  parentheses when the method doesn't accept any arguments.

     ```Ruby
     def some_method
       # body omitted
     end

     def some_method_with_arguments(arg1, arg2)
       # body omitted
     end
     ```

* Never use **for**, unless you know exactly why. Most of the time iterators
  should be used instead.

    ```Ruby        
    arr = [1, 2, 3]
        
    # bad
    for elem in arr do
      puts elem
    end

    # good
    arr.each { |elem| puts elem }
    ```
    
* Never use **then** for multiline **if/unless**.

    ```Ruby
    # bad
    if x.odd? then
      puts "odd"
    end

    # good
    if x.odd?
      puts "odd"
    end
    ```

* Favor **if/then/else** over the ternary operator. *if* is an
  expression in Ruby and the resulting code is arguably easier to
  read (albeit not as concise). Remember that _"Programs must be written for
  people to read, and only incidentally for machines to execute."_ (Abelson
  and Sussman)

    ```Ruby
    # good
    result = if some_condition then something else something_else end

    # not so good
    result = some_condition ? something : something_else
    ```

* Use **when x; ...** for one-line cases.
* Use **&&/||** for boolean expressions, **and/or** for control flow.  (Rule
  of thumb: If you have to use outer parentheses, you are using the
  wrong operators.)

    ```Ruby
    # boolean expression
    if some_condition && some_other_condition
      do_something
    end

    # control flow
    document.saved? or document.save!
    ```

* Avoid multiline ?: (the ternary operator), use **if/unless** instead.
* Favor modifier **if/unless** usage when you have a single-line
  body. Another good alternative is the usage of control flow **and/or**.

    ```Ruby
    # bad
    if some_condition
      do_something
    end

    # good
    do_something if some_condition

    # another good option
    some_condition and do_something
    ```

* Favor **unless** over **if** for negative conditions (or control
  flow **or**).
       
    ```Ruby
    # bad
    do_something if !some_condition

    # good
    do_something unless some_condition

    # another good option
    some_condition or do_something
    ```
    
* Suppress superfluous parentheses when calling methods, but keep them
  when calling "functions", i.e. when you use the return value in the
  same line.
  
    ```Ruby
    x = Math.sin(y)
    array.delete e
    ```
        
* Prefer {...} over do...end for single-line blocks.  Avoid using {...} for
  multi-line blocks.  Always use do...end for "control flow" and "method
  definitions" (e.g. in Rakefiles and certain DSLs.)  Avoid do...end when
  chaining.

* Avoid **return** where not required.

    ```Ruby
    # bad
    def some_method(some_arr)
      return some_arr.size
    end

    # good
    def some_method(some_arr)
      some_arr.size
    end
    ```

* Avoid line continuation (\\) where not required. In practice, avoid using
  line continuations at all.

    ```Ruby
    # bad
    result = 1 + \
    2

    # good (but still ugly as hell)
    result = 1 \
    \+ 2
    ```

* Using the return value of = is okay.

    ```Ruby
    if v = array.grep(/foo/) ...
    ```

* Use ||= freely.

    ```Ruby
    # set name to Bozhidar, only if it's nil or false
    name ||= "Bozhidar"
    ```

* Avoid using Perl-style global variables (like $0-9, $`, ...).

## Naming

* Use snake_case for methods and variables.
* Use CamelCase for classes and modules.  (Keep acronyms like HTTP,
  RFC, XML uppercase.)
* Use SCREAMING_SNAKE_CASE for other constants.
* The length of an identifier determines its scope.  Use one-letter variables
  for short block/method parameters, according to this scheme:

        a,b,c: any object
        d: directory names
        e: elements of an Enumerable
        ex: rescued exceptions
        f: files and file names
        i,j: indexes
        k: the key part of a hash entry
        m: methods
        o: any object
        r: return values of short methods
        s: strings
        v: any value
        v: the value part of a hash entry
        x,y,z: numbers

  And in general, the first letter of the class name if all objects are of
  that type.

* When using **inject** with short blocks, name the arguments **|a, e|**
  (accumulator, element).
* When defining binary operators, name the argument **other**.

    ```Ruby
    def +(other)
      # body omitted
    end
    ```
    
* Prefer **map** over *collect*, **find** over *detect*, **find_all** over
  *select*, **size** over *length*. This is not a hard requirement; if the
  use of the alias enhances readability, it's ok to use it.

## Comments

* Write self documenting code and ignore the rest of this section.
{'fraction_non_alphanumeric': 0.09191425858092525, 'fraction_numerical': 0.0096323429656763, 'mean_word_length': 2.4510767790262173, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '692499', 'n_tokens_mistral': 4588, 'n_tokens_neox': 4261, 'n_words': 1893}