Manual:Coding conventions/Ruby

This article describes the coding conventions for Ruby files of MediaWiki related codebases.

Unlike Python with its PEP 8, Ruby has no truly canonical style guide to which to reference. There are, however, a few well respected guides that can serve as reference points for Rubyists, most prominently those from GitHub, Heroku, and the community-driven guide from bbatsov.

Starting Point
For reasons both public-spirited and practical, we have adopted the bbatsov guide as a starting point; it's the most participatory of the three and comes with the rubocop code analyzer that can be easily customized and integrated into our continuous integration.

Exceptions
Exceptions and additions to the bbatsov guide are enumerated herein.

Aliasing Methods

 * RuboCop ID :
 * Enforced : no

The bbatsov guide suggests that  should always be used over. However, there are cases where  can be just as clear or even more appropriate when written alongside methods defined with.

In short, it's ok to use  within the body of a class or module definition to alias a method also defined therein. However, it should not be used to alias methods defined by a macro;  is more appropriate in that case since it's a macro itself.

Multi-line Method Chaining

 * RuboCop ID :
 * Enforced : per project

Two options are presented in the bbatsov guide. We allow either form as long as you stay consistent within each project.

Signaling Exceptions

 * RuboCop ID :
 * Enforced : no

The bbatsov guide suggests using  to signal new exceptions and   to re-raise rescued ones. However, there's some objection to the rule based on the lack of the former in existing Ruby projects or prominent Ruby literature and the contrived nature of useful semantic differences given as justification. For now, we don't enforce this rule.