Rubyisms: naming conventions

August 1, 2006

Today I wanted to show the implicit and explicit naming conventions in Ruby for newbies. It isn't particularly consistent with another language's conventions, so could cause confusion when reading the Ruby Standard Library (RSL). Where appropriate I also discuss how some of the naming conventions really aid code readability and developer productivity.

ClassName and ModuleName [implicit]

Naming classes is very similar to most common conventions following in C++, Java, Python and C#. For example: DataMigration, CorporateConvertibleBond, =Controller, etc.

I am unaware of a class name in the Ruby Standard Library (RSL) that violates this rule. RSL examples of convention usage are Fixnum, Rational, DateTime, Module, NameError, NotImplementedError, NilClass. I realize Fixnum is a little controversial, but I think there is a case for its naming as above.

variable_name and regular_method_name [implicit]

For variable names and methods that do something that isn't dangerous and/or return a non-boolean to the caller, the common underscoring convention is used to name them. This is consistent with Perl and PHP variable naming conventions.

RSL examples include: String#strip, Object#instance_eval, Array#sort_by.

method_asking_a_question? [implicit]

Suffixing a method that asks a question with a '?' is a great way to tell clients of your code it returns a boolean value to be used in conditional expressions.

My favorite RSL example is Object#nil?. This is one of the most important methods, in my mind, that exist in Ruby in conjunction with making Ruby's None, null, NULL equivalent, nil an object of the type NilClass.

RSL exaples include: Object#is_a?, Hash#has_key?, Object#frozen?.

This naming approach is my joint favorite with the following convention that significantly increases readability of code and implicitly improves developer productivity as a side effect.

slightly_dangerous_method! [implicit]

For methods that change the internal state of the object in a way that may not be apparent, a '!' is suffixed to the method name to follow this convention.

As an example in the RSL, you would probably expect the call "a string".upcase to return a copy of the original string in upper case, but the call "a string".upcase! warns you via the bang (!) that the original object's internal state is changing. This informs developers writing the code of the String class what the implications are.

This naming convention will keep you out of trouble. If a team mate decides to try out some of your APIs, then you can feel safe knowing you have warned him/her of potential danger spots.

@instance_variable [explicit]

Instance variables are explicitly prefixed with the '@' sign. Some may thing this is a Perlism that crept over, but in Perl '@' prefixed variables referred to arrays, if I remember correctly, so the usage is quite different. It should be noted that the '@' prefix is only used when referring to instance variables internally within the class.

Using the '@' prefix does provide a convenient visual que that I am using an instance method which definitely improves readability of code.

$global_variable [explicit]

To refer to global variables prefix the name with '$'. This is an explicit naming convention in Ruby, much like the '@' prefix for instance variables above. This gives a quick visual note that we are knowingly using globals. For me it also provides a psychological check, where I start to question my motives whenever using a global variable and usually end up refactoring code to avoid using globals.

SOME_CONSTANT or OtherConstant [kind of explicit:)]

Much like in Java and Python, Ruby's constant naming convention is not commonly consistent. Often developers use the capilized naming approach, while just as many use the camel case convention used for class and module names in Ruby.

Personally, if the constant is accessible from the module or class, I default to using the former approach unless the project has a different preference. For internally accessible constants, it is probably a moot point.

All in all I find using these or very close naming conventions to those listed here, help me become more productive as a Ruby developer. I also find it useful to notice the Ruby mindset of being as expressive as possible without being verbose implicitly defined in the naming rules above.