/styleguide

Christian Neukirchen's Ruby Style Guide

This is a fork of Christian Neukirchen's Ruby Style Guide, with some of my personal preferences. The original can be found here.

Formatting:

  • Use ASCII (or UTF-8, if you have to).

  • 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 ], ).

  • Indent when as deep as case.

  • 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 like the plague.

Syntax:

  • Use def with parentheses when there are arguments.

  • Never use for, unless you exactly know why.

  • Avoid multiline ?:, use if.

  • Use parentheses when calling methods when they're worded as commands or look like "functions". For example:

    x = Math.sin(y)
user = User.find(3)
point.translate(0, 1)

    Avoid parentheses when the method call has a DSL feel and is alone on the line, like:

    has_many :users
link_to "Foo", bar_path
collection.include? 3

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

Naming:

  • Use snake_case for methods.

  • Use CamelCase for classes and modules. (Keep acronyms like HTTP, RFC, XML uppercase.)

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

Comments:

  • Comments longer than a sentence are capitalized and use punctuation.

  • Avoid superfluous comments.

The rest:

  • Avoid long methods.

  • Avoid long parameter lists.

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

  • Write for 1.8, but avoid doing things you know that will break in 1.9.

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

  • Avoid bugs.

  • Read other style guides and apply the parts that don't dissent with this list.

  • Be consistent.

  • Use common sense.