Coding Guidelines

gistfile1.txt

## Versioning

* Version using [Semantic Versioning](http://semver.org/) spec.

## Code

### Formatting

* Use UTF-8.

* Use 2 space indent, no tabs.

* Use Unix-style line endings.

* Use spaces around operators, after commas, colons and semicolons,
  around { and before }.

* No spaces after ( and before ).

* Use spaces after [, { and before ], }.

* Use one space before statement modifiers (postfix
  if/unless/while/until/rescue).

* Indent when as deep as case.

* Use an empty line between defs.

* Use [TomDoc](http://tomdoc.org/) 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.

### Syntax

* Use def with parentheses when there are arguments.

* Never use for, unless you exactly know why.

* 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.)

* Avoid multiline ?:, use if.

* 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)
    puts x
    ```
* Prefer {...} over do...end. Use do...end for multiline blocks.
  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.

* 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.

### 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`,
  `size` over `length`.

### Commits

* In Git, merge branches via `rebase` (i.e., `git merge advanced-search --rebase`)

* Write good commit messages where possible. A model of a good commit message is:

```
    Capitalized, short (50 chars or less) summary

    More detailed explanatory text, if necessary.  Wrap it to about 72
    characters or so.  In some contexts, the first line is treated as the
    subject of an email and the rest of the text as the body.  The blank
    line separating the summary from the body is critical (unless you omit
    the body entirely); tools like rebase can get confused if you run the
    two together.

    Write your commit message in the present tense: "Fix bug" and not "Fixed
    bug."  This convention matches up with commit messages generated by
    commands like git merge and git revert.

    Further paragraphs come after blank lines.

    - Bullet points are okay, too

    - Typically a hyphen or asterisk is used for the bullet, preceded by a
      single space, with blank lines in between, but conventions vary here

    - Use a hanging indent
```

### 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 singleton methods.

* Add "global" methods to Kernel (if you have to) and make them private.

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

* Avoid needless metaprogramming.

### General

* Code in a functional way, avoid mutation when it makes sense.

* Do not mutate arguments unless that is the purpose of the method.

* 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.

* Be consistent.