Rubyisms: naming conventions

Written on 12:43:00 PM by S. Potter

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#. e.g. DataMigration, CorporateConvertibleBond, Controller etc. I am unaware of a class name in the (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 it's 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. Please note this is the one convention listed here that is violated in the RSL the most.

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 and object of 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 method "a string".upcase to return a copy of the original string in upper case, but the method "a string".upcase! would probably warn you that it would change the original object's internal state. This is an important distinction to know as a developer writing client code to the String class. 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.

If you enjoyed this post Subscribe to our feed

No Comment

Post a Comment