Ruby Style Guide

_ Fork of Christian Neukirchen's Ruby Style Guide. Edited/Modified to suit my style. _

h1. Ruby Style Guide

h2. Formatting:

* Use ASCII (or UTF-8, if you have to).
* Use an empty line before the return value of a method (unless it
  only has one line), and an empty line between defs.

* 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 long method into logical paragraphs.
* Keep lines fewer than 80 characters.
* Avoid trailing whitespace.

h2. Spacing

* Use 2 space indent. No tabs. (See #vim settings section below)
* Use spaces around operators (Arithmetic and Logical)
* Use spaces after commas, colons and semicolons
* Use spaces around { and before }
* No spaces after (, [ and before ], ).

h2. Syntax:

* Use def with parentheses when there are arguments.
* Never use for.
* Never use then.
* Use when x; ... for one-line cases.
* Use &&/|| for boolean expressions, and/or for control flow.
* Avoid multiline while using ternary operator (?:)

* Suppress superfluous parentheses when calling methods, but keep them
  when calling "functions", i.e. when you use the return value in the
  same line.

    x = Math.sin(y)
    array.delete e

* Prefer {...} over do...end.  Multiline {...} is fine: having
  different statement endings (} for blocks, end for if/while/...)
  makes it easier to see what ends where.  But 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.
* Avoid line continuation (\) where not required.
* Using the return value of = is okay:

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

* Use ||= freely.
* Use non-OO regexps (they won't make the code better).  Freely use
  =~, $0-9, $~, $` and $' when needed.

h2. Naming:

* Use snake_case for methods.
* 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.

* Use _ or names prefixed with _ for unused variables.
* When using inject with short blocks, name the arguments |a, e|
  (mnemonic: accumulator, element)
* When defining binary operators, name the argument "other".
* Prefer map over collect, find over detect, find_all over select.
* Avoid short variables unless they are in a block scope.
* Avoid cryptic naming. Let the method names and variable 
  names be meaningful even if they are long.

h2. Comments:

* Comments longer than a word are capitalized and use punctuation.
  Use two spaces after periods.
* Avoid superfluous comments. Use meaningful method names to avoid comments.

h2. The rest:

* Write ruby -w safe code.
* Avoid hashes-as-optional-parameters.  Does the method do too much?
* Avoid long methods.
* Avoid long parameter lists.
* Use def self.method to define one off singleton methods.
* Use class << self; ... to write more than one singleton methods
* Add "global" methods to Kernel (if you have to) and make them private.
* Avoid alias when alias_method will do.

* Use OptionParser for parsing complex command line options and
  ruby -s for trivial command line options.

* Write for 1.8, but avoid doing things you know that will break in 1.9.
* Avoid needless metaprogramming.

h2. General:

* Code in a functional way, avoid mutation when it makes sense.
* Do not mess around in core classes when writing libraries.
* Do not program defensively.
  (See http://www.erlang.se/doc/programming_rules.shtml#HDR11.)

* Keep the code simple.
* Don't overdesign.
* Don't underdesign.
* Don't code for future. Follow YAGNI.
* Avoid bugs.
* Be consistent.
* Use common sense.