RUBY-STYLE

= Benjamin Kudria's Ruby Style Guide (with apologies to Christian Neukirchen)

You may not like all rules presented here, but they work very well for me and have helped producing high quality code.

However, this is a guide, not a rule book.  Absolutism makes no sense.  Every rule is not only meant to be broken, it needs to be, as often and as vigorously as possible.

Some of these rules contradict others. That's intentional. Reality is so far beyond our comprehension it's not even funny.

These rules will change in the future.

Everyone is free to code however they want, write and follow their own style guides, but when contributing to my code try to follow these rules:


== Formatting:

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

* Use one tab indent, spaces to align.  No tabs after spaces.

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

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

* If you need empty lines to break up a long method into paragraphs, consider having more than one method. Otherwise, they are OK.

* Ignore the 80-line limit, but try not to have lines too long.

* Avoid trailing whitespace.


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

* Add parentheses in logical statements to avoid potential confusion for someone who may not know all the rules.

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

* Avoid complex regexps if at all possible. If not, use OO regexps.  Avoid using =~, $0-9, $~, $` and $' - use the named variants instead.


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

* Avoid one-letter or otherwise abbreviated variable names. Avoid generic variable names unless you are writing generic code (e.g.: object, value, exception, element, index, file, key, string, number, etc)

* Don't use unused variables. Warning sign: anything prefixed with an underscore.

* When defining binary operators, name the argument "other".

* Prefer map over collect, find over detect, find_all over select.


== Comments:

* Comments longer than a word are capitalized and use punctuation. Use one space after periods. Punctuation goes inside parentheses.

* Avoid superfluous comments. Avoid comments explaining what the code is doing literally.  Avoid comments altogether, if possible: name your variables and methods better. If you must have comments, they had better be explaining the *why*, not the how or, deity forbid, what.


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

* Do not add global methods to Kernel. Put it in a module instead.

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

* Avoid needless metaprogramming, no matter how fun it is.


== 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 enough (but no simpler)

* Don't design.

* Accept that there will be bugs: test.

* Be consistent unless it makes sense not to.

* Use common sense unless it makes sense not to.

(Comments, mistakes, and hysterical finger-pointing appreciated.)