Manual:Coding conventions/Ruby

This article describes the coding conventions for Ruby files of MediaWiki related codebases. For general conventions used across all languages and MediaWiki projects, first refer to Manual:Coding conventions. Some guidelines covered therein may be repeated for clarity.

Unlike Python with its PEP 8, Ruby has no truly canonical style guide to which to reference. Instead, this article will attempt to coalesce a number of well respected guides with the informed opinions and common practices of those in the MediaWiki community and Wikimedia Foundation staff.

Encoding
All source files should be encoded in either ASCII or UTF-8. Those containing multibyte sequences should declare use of UTF-8 using an  comment on the first line. Although Ruby 2.0 and up use UTF-8 as the default encoding, version 1.9 defaults to ASCII, and earlier versions are encoding unaware. We can mitigate inconsistent behavior on different systems using this explicit declaration.

Naming
For methods, variables, symbols, keyword arguments, and filenames use.

For class and module names, use. (Whether or not to leave acronyms uppercase is somewhat contentious.)

For constants, use.

Predicate methods should end with a question mark and should not begin with redundancies such as  or.

Indentation
Use two spaces per indentation level, no hard tabs.

Line Length
Keep comment lines under 80 characters in length, and lines of code under 100.

Operators
Use single spaces around assignment and infix operators. Leave no space after prefix operators.

Separators
Use single spaces after commas, colons and semicolons, after, and before  , and around the  's for block arguments. Leave no space after prefix operators, after  and , and before   and.

Vertical Spacing
Leave blank lines between module, class and method definitions. Use logical paragraphs to break up other implementation if it improves readability.

Files
Names of directories and file names should match the snake-case equivalents of the modules and classes defined therein.

Files should typically define only one module or class. Exception definitions are a common... exception to this rule, but should be defined elsewhere once they grow in numbers.

Classes and Modules
Class definitions should adhere to this basic pattern.

Methods
Always omit parentheses from method definitions with no arguments.

Always include parentheses in method definitions with arguments.

Avoid explicit use of  when it's not required.

Methods
Always omit parentheses when calling methods with no arguments.

Whether or not to include parentheses in method calls that contain arguments is a subject of great debate among Rubists. Some consider them clutter and use them only where strictly necessary, while some will outright suggest they are required. Others take a more middle-ground stance that attempts to divide the issue into two semantic use cases. The latter is what we'll adopt.

If the method invocation is part of an expression where one could conceivably care about its return value, include the parentheses. Conversely, if the invocation is purely statement-like, part of a descriptive DSL, or uses a built-in like  or , then omit the parentheses. In a way, we're establishing a convention to delineate between statement-like imperative patterns in Ruby, and more functional ones.

In other words: "So, parentheses actually subtly signal something semantic about your code. They say: “Hey, I’ve got a value. You might want to use it.” Likewise, a lack of parentheses says something, too: “Sorry, I’ve got no value for you to use - I’m all about my side-effects.”"

And, of course, always conform to syntax and precedence rules where required. For example, a method call that includes both arguments and a bracket-syntax block will require parentheses because of the otherwise ambiguous block receiver.

Statement Examples
The ubiquitous use of statement-like.

Although,  , and   are technically methods (respectively  ,  , and  ) they are almost always used in a statement-like way.

Most module-level methods (aka macros) are statement like.

Frameworks such as RSpec or Rails often use statement-like DSLs.

Always use parenthesis to clarify ambiguous precedence.