Ruby Coding Guidelines¶
Strongly based on https://github.com/chneukirchen/styleguide/ with some local changes.
Formatting:¶
- Use UTF-8 encoding in your source files.
- Use 2 space indent, no tabs.
- Use Unix-style line endings, including on the last line of the file.
- Use spaces around operators, after commas, colons and semicolons, around { and before }.
- No spaces after (, [ and before ], ).
- Prefer postfix modifiers (if, unless, rescue) when possible.
- Indent when as deep as case then indent the contents one step more.
- Use an empty line before the return value of a method (unless it only has one line), and an empty line between defs.
- Use Yard and its conventions for API documentation. Don’t put an empty line between the comment block and the definition.
- Use empty lines to break up a long method into logical paragraphs.
- Keep lines shorter than 80 characters.
- Avoid trailing whitespace.
Syntax:¶
- Use def with parentheses when there are arguments.
- Conversely, avoid parentheses when there are none.
- Never use for, unless you exactly know why. Prefer each or loop.
- Never use then, a newline is sufficient.
- Prefer words to symbols.
- and and or in place of && and ||
- not in place of !
- Avoid ?:, use if (remember: if returns a value, use it).
- Avoid if not, use unless.
- Suppress superfluous parentheses when calling methods, unless the method has side-effects.
- Prefer do...end over {...} for multi-line blocks.
- Prefer {...} over do...end for single-line blocks.
- Avoid chaining function calls over multiple lines (implying, use {...} for chained functions.
- 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 for memoization.
- When using regexps, freely use =~, -9, :math:`~, ` and $` when needed.
- Prefer symbols (:name) to strings where applicable.
Naming:¶
- Use snake_case for methods.
- Use CamelCase for classes and modules. (Keep acronyms like HTTP, RFC and XML uppercase.)
- Use SCREAMING_CASE for other constants.
- 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 or a rescued Exception
- f: files and file names
- i,j: indexes or integers
- 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
- And in general, the first letter of the class name if all objects are
of that type (e.g.
nodes.each { |n| n.name }
) - Use _ for unused variables.
- When defining binary operators, name the argument other.
- Use def self.method to define singleton methods.
Comments:¶
- Comments longer than a word are capitalized and use punctuation. Use two spaces after periods.
- Avoid superfluous comments. It should be easy to write self-documenting code.
Code design¶
- Avoid needless meta-programming.
- Avoid long methods. Much prefer to go too far the wrong way and have multiple one-line methods.
- Avoid long parameter lists, consider using a hash with documented defaults instead.
- Prefer functional methods over procedural ones (common methods below):
- each - Apply block to each element
- map - Apply block to each element and remember the returned values.
- select - Find all matching elements
- detect - Find first matching element
- inject - Equivalent to foldl from Haskell
- Use the mutating version of functional methods (e.g. map!) where applicable, rather than using temporary variables.
- Avoid non-obvious function overloading (e.g. don’t use [“0”] * 8 to initialize an array).
- Prefer objects to vanilla arrays/hashes, this allows you to document the structure and interface.
- Protect the internal data stores from external access. Write API functions explicitly.
- Use attr_accessor to create getters/setters for simple access.
- Prefer to add a to_s function to an object for ease of debugging.
- Internally, use standard libraries where applicable (See the docs for the various APIs).:
- Hash, Array and Set
- String
- Fixnum and Integer
- Thread and Mutex
- Fiber
- Complex
- Float
- Dir and File
- Random
- Time
- Prefer string interpolation “blah#{expr}” rather than appending to strings.
- Prefer using the %w{} family of array generators to typing out arrays of strings manually.
General:¶
- Write ruby -w safe code.
- Avoid alias, use alias_method if you absolutely must alias something (for Monkey Patching).
- Use OptionParser for parsing command line options.
- Target Ruby 2.0 (except where libraries are not compatible, such as Chef).
- 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.
- Be consistent.
- Use common sense.