Coding in Ruby - mostly the Gus way

ruby-coding-style.md

Hijacked from Christian Neukirchen's Ruby Style Guide

Coding in Ruby

These are guides, not rules. There are always reasons to not do something, but if you can stay on this road for as long as possible, at least Gus will be happy.

General

• Use common sense.
• Be consistent.
• Red, green, refactor, refactor, refactor.
• Refactor your tests.
• 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
• Keep the code simple. Don't overdesign. Don't underdesign.
• Read other style guides and apply the parts that don't dissent with this list.

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 ], )
• Use one space before statement modifiers (postfix if/unless/while/until/rescue)
• Indent when as deep as case
• If you have more than 3 levels of indentation within a method, this is unreadable. Break some functionality into its own method
• Don't put an empty line between the comment block and the def. Document however you like, but YARD or RDoc are pretty good formats
• If you're method is longer than 10 lines, look for functionality that should be in its own method
• Line breaks at 120 characters. None of this 80 character nonsense
• Feel free to write single line defs, so long as there is only one statement: def foo; "bar"; end
• Use an empty line between defs, unless your defs are written in single line form
• Avoid trailing whitespace, but do put a newline at the bottom of your files

Syntax:

• Use def with parentheses when there are arguments.
• Never use for, unless you exactly know why.
• Never use then.
• 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.)
• Avoid multiline ?:, use if.
• Prefer {...} over do...end, but use do...end for multiline blocks.
• 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.

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.
• Spell out your variable names in plain english. Reserve one letter variables for obvious temporary variables within block statements; such as: array.map {|e| e.to_s}
• When using inject with short blocks, name the arguments |acc, e| (mnemonic: acc, 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 word are capitalized and use punctuation. Use one space after periods.
• Avoid superfluous comments.

The rest:

• Use a require as close to the source of where it is used as you can.
• Write ruby -w safe code.
• Avoid hashes-as-optional-parameters. Does the method do too much?
• 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.
• Write for ruby 1.9.
• Avoid needless metaprogramming, but don't be afraid of it.