Elements of Ruby Style

 

1.              Notes on Ruby Composition

a.     Organizational Composition

                                               i.     Code should be broken into files, then modules, classes, etc.

                                             ii.     Files should end in .rb

                                            iii.     File organization

                                            iv.     Files should group classes and modules that are directly related; the preferred form is to have one file for one class that is named for the class

                                             v.     Modules should group methods that will be mixed into other classes

                                            vi.     Rather than duplicating a number of classes and methods, create a module and mix it in to each class that needs that functionality.

                                          vii.     Classes should group together methods and values that form objects

                                         viii.     Namespace your code with modules to avoid stomping on others’ code (and use include to stomp on it)

                                            ix.     Libraries should be built from related classes that perform a single function

                                             x.     Libraries should not be put in a currently existing directory, but put into a central, dedicated directory

b.     Formatting

                                               i.     Place whitespace on either side of = when assigning

                                             ii.     Do not put whitespace when assigning default parameters

                                            iii.     Keep spaces balanced

                                            iv.     Attempt to line up = when there are many of them in a row

                                             v.     Put two spaces instead of tabs

                                            vi.     Put two blank lines between class and module definitions and a single line between method definitions

                                          vii.     Do not put spaces between method calls and parameter list

c.     Line composition

                                               i.     No single line of code should be over 80 characters, except for long regular expressions or external method names

                                             ii.     Assignment shouldn’t be paralelled unless a paralell method return is used or reference is desired

                                            iii.     Though Ruby allows it, do not use semicolons to end lines

                                            iv.     Rather than creating new objects, chain method calls

2.              Code in Style

a.     Values

                                               i.     Variables should be initialized

                                             ii.     Don’t use global variables; variables should be properly scoped

                                            iii.     Variables and constants shouldn’t be named single charaters except for iterators and counters

                                            iv.     Variable and constant names should be nouns

                                             v.     Constant names should be all capitals

                                            vi.     Use proper methods for testing for empty or false values

                                          vii.     Initialize a variable with either a value or the constructor form to promote readability

b.     Methods

                                               i.     Methods should be declared public, private, or protected as appropriate

                                             ii.     Method names should be all lower case letters and underscores

                                            iii.     Method names should be descriptive verbs

                                            iv.     Methods that alter an object in place should end with !

                                             v.     Methods that query an attribute and return a boolean value should end with ?

                                            vi.     If a your method has a block parameter, try to use yield rather than accepting it as a variable and calling call on it.

                                          vii.     Use default parameter values rather than early initialization

                                         viii.     Avoid long argument lists; instead allow passing of a params object or an argument hash

                                            ix.     Methods should be the basis of functionality, and as such should only do one thing. Make more methods if needed.

                                             x.     Use named arguments for long lists

c.     Blocks

                                               i.     Braces should be used on one line blocks; do/end form should be used on multi-line blocks

                                             ii.     Curly braces should be used if the return value is desired

                                            iii.     Use parametrized variables rather than accessing scope variables

d.     Classes

                                               i.     Classes should be named in Pascal case

                                             ii.     Class names should be nouns

                                            iii.     Do not use set_* or get_* methods; rather, use attr_* to access instance variables

                                            iv.     Use standard method names for standard behavior, like each or eql?

                                             v.     Implement inspect

e.     Exceptions

                                               i.     Use try catch to control flow rather than rescue blocks

f.      Conditionals

                                               i.     Use chaining operators rather than nested if statements where possible

                                             ii.     When wrapping blocks with if statements, use statement modifier form rather than opening another block

                                            iii.     Use the statement modifier form rather than a one line block where possible

                                             iv.     Use case statements instead of multiple if statements

                                            v.     when statements don’t need break

g.     Flow Control

                                               i.     Use iterators rather than loops and indices

                                             ii.     Use statement modifiers rather than one line loops

h.     Strings

                                               i.     There is no advantage to using single quotes or double quotes other than safety

                                             ii.     Don’t combine string literals and variables using +; rather, use interpolation

                                            iii.     Multi-line strings should be expressed using here-docs rather than shoving it in a quoted string (unless this affects readability or you need interpolation, in which case you should insert \n in a double quoted string)

3.              Some Notes about Ruby Idioms

a.     System Interaction

                                               i.     Don’t call an external program for something Ruby has a library for (unless the library is incomplete)

                                             ii.     Call the binaries in the most portable way possible, making use of environment variables where possible

                                            iii.     Use the right call (i.e., if you need output, etc.)

                                            iv.     Don’t pass user input to external programs or dangerous, system altering code without first cleaning it

b.     Best Practices

                                               i.     Use blocks to transact resources and close them when you’re done

                                             ii.     Include Enumerable if you plan to offer an iterator

                                            iii.     Include Comparable if you plan to implement <=>

                                            iv.     Use += rather than x = x + y

                                             v.     Use iterators rather then loops and indexes