Class variables behave a lot like global variables — discussed later in this article — except they are scoped within their own class hierarchy rather than globally. For a closer look, consider the following:

Notice both the Parent and Child classes yield the same output, which seems reasonable until the following modification is introduced:

Not only did the Child define it’s own value but it mutated the Parent as well. If you haven’t seen this before, it can be an unpleasant surprise. A quick and dirty solution would be to instead use a class instance variable:

While the above is an improvement, a better approach would be remove state from classes altogether and encapsulate behavior in a barewords instance:

As an added bonus, you now have a way to construct multiple instances of each class with different default messages.

It is worth noting that with Ruby 3.0.0 you’ll get a RuntimeError if attempting to re-assign a variable owned by another class in the hierarchy:

The same is true, with Ruby 3.0.0, if a module attempts to change the class variable:

Even with improved support in Ruby 3.0.0, use of class variables should be avoided. As an aside, there was a glimmer of hope that class variables would be removed from the language entirely but Matz stepped in with the final word:

A flat module structure looks like this:

Notice when we print the module structure at point of call we get a single element array: One::Two::Three. To contrast the above, here’s the result when defining nested modules:

Now we have a three element array where each module in the hierarchy is a unique element in the array. Our object hierarchy is preserved so constant/method lookup is relative to the hierarchy. To illustrate further, consider the following:

As the error above shows, we could use One::Example to solve the problem. To not repeat ourselves, use a nested module structure instead:

Notice how the above is concise, removes duplication of the earlier example, and provides a unique constant for each level of the hierarchy for relative reference and lookup. Stick to nested modules so you can avoid needless implementation construction and unexpected errors.

Ruby has a collection of global variables which are borrowed from Perl and shell scripting, in general. These can be viewed via the Kernel#global_variables method. A full description of all variables and their corresponding aliases can be found within the English library source code (i.e. require "English"). Here’s a rough breakdown of each:

You can also define and use your own global variables:

Global variables are good to be aware of but suffer from several issues:

Requiring the English library will improve readability but doesn’t prevent the values from being mutated unless you remember to freeze them. A better approach is to reduce scope to the objects that need these values through dependency injection via default constants or even default configurations provided by gems like XDG or Runcom.

In some situations, it can be tempting to automatically load a constant when a constant is not found. Example:

The problem with the above is that this can lead to malicious behavior where a hacker could exploit the above by attempting to load unexpected code. Here are further examples:

Dynamically loading constants or other objects can be useful in limited situations. To prevent malicious attacks, ensure safety checks are put in place. For example, all of the above could be avoided with the following check:

The dynamic nature of Ruby provides great power but with this this power comes great responsibility. When reaching for functionality like this, keep usage limited along with restricted access to narrow any potential for exploit.

The Kernel module is powerful and convenient module which provides syntactic sugar for common situations that requires less typing and/or setup if Kernel did not exist. That said, it comes with sharp edges. One of them being Kernel.open which provides a quick way to open a file or URL. The only problem this is method is cause for a lot of security issues which are best explained and documented in this Ruby Issue.

You are much better off using IO.popen or URI.open in these situations since they are more secure.

When using ERB (or any templating language supported by Tilt), ensure you avoid using <%== %> or <%= raw %> in your templates or, if your framework provides it, #html_safe. All of these techniques avoid proper sanitization of malicious content, usually from user input, which is a huge security risk to your product/service. Instead, lean on your framework to sanitize input so you can avoid Cross-Site Scripting attacks altogether. Usually your framework will provide this for you via a #sanitize method. Whatever it might be called, please use it.

More often than not, NotImplementedError is incorrectly used in inheritance where you need to ensure a subclass implements a method that isn’t provided by the superclass. Example:

The problem is NotImplementedError isn’t meant for this use case because NotImplementedError is meant for situations where you don’t support the current platform. Here’s the official API documentation:

The other problem is NotImplementedError doesn’t inherit from StandardError but ScriptError. The correct way to handle this situation is to use NoMethodError which does inherit from StandardError. You can see this more clearly in the ancestry of each error:

The corresponding NoMethodError API documentation emphasizes this further:

Armed with the above information, ensure you use NoMethodError for these situations, or avoid exceptions altogether and provide a fallback implementation in your abstract class if that makes better sense, instead of using NotImplementedError.

When chaining multiple messages together, default to using a single line as long as the line doesn’t violate your style guide’s column count. In situations where you need to use multiple lines for message changes — and this is important — ensure all messages are vertically aligned by dot notation so it’s easier to read through each step of the message chain (as shown in the examples below). For instance, take the following which reads from a file and splits on new lines:

The above is short and readable but if the implementation became more complex, you’d risk violating your column count and incur a horizontal scrolling cost to read through the implementation. By breaking up your messages per line and vertically aligned by dot notation, you improve readability. Example:

You’ll also want to break your message chains into single lines when using anonymous functions. Example:

While the one-liner is syntactically correct, it decreases readability. Even worse, imagine a one-liner with multiple anonymous functions all chained together on a single line. The readability and maintainability would get out of hand rather quickly. One common example of multiple anonymous functions chained together is when using RSpec. Take the following example:

The above abuses dot notation to chain together multiple anonymous messages. A better solution is to use local variables to reduce complexity. Example:

While the above incurs a local variable cost, the trade-off is that the entire expectation is readable via a single line. 🎉

There is an obscure style worth mentioning which is Jim Weirich’s semantic rule for {} versus do...end. The semantic rule is less common and much harder to enforce. Plus, as you’ve seen above, there is value in being able to use {} for message chains that might return a value or cause a side effect in terms of readability and succinctness.

Finally — and related to the above — when needing to chain a multi-line anonymous function, ensure the call is at the end of a message chain. Example:

While the above is a contrived example, you see how readability improves as the eye traces — top to bottom — through the dot notation with the multi-line do…​end signaling the end of the chain. Should you need multi-line functionality in the middle of your message chain, then you can give this functionality a name by using a method. Example:

The lazy operator — or more formally known as the Safe Navigation Operator — was introduced in Ruby 2.3.0. This operator is particularly egregious because it makes code hard to read and leads to defensive coding when we could be writing Confident Code instead. Here’s an example:

Example:

When you take the above and decompress it, you end up with the following nested logic:

That’s a lot of defensive coding because with author&.address&.zip we have a hard time discerning what this code is trying to say:

The above violates/encourages all of the following:

💡 You can ensure the Lazy Operator is never used by adding the Caliber gem to your project as part of your code quality checks.

You can cast objects to different types through explicit (standard) and implicit (rare) casting. Here’s a quick breakdown of primitive types with their explicit and implicit equivalents:

Where this goes terribly wrong is when implicit casting is misused as the object’s primary API. Example:

Notice the implicit #to_str method is explicitly called. Ruby will happily evaluate your implementation but explicitly messaging an implicit method, as shown above, should be avoided. Here’s a more appropriate implementation:

Notice #to_s is the explicit implementation provided for downstream callers while the implicit #to_str method is an alias of #to_s so Ruby can perform the implicit casting of version to a string when printed on the last line. Without the implicit alias, you’d end up with a TypeError.

The main point here is to always default to implementing the explicit version of the type you desire while only aliasing implicit support if you want to allow Ruby to conveniently cast your object into another type without having to force explicit use.

Should you want a fully fledged implementation of the Version implementation show above with additional examples, I encourage you to check out the Versionaire gem.

Class methods — also known as singleton methods — often get abused when used to answer literals and static values in general. Example:

While tempting to use a class method for this information, a constant is meant for this exact purpose which means the above can be rewritten as follows:

Notice, with the above, that the ROLE constant is now used to define the default role which then can be easily injected and asked for via the #role instance method. This provides several advantages:

Introduced in Ruby 3.0.0, these should not be used for multi-line message chains:

Instead, it is better to use a normal method if multiple lines are necessary:

Even better, if an endless method can fit on a single line then use the single line:

This improves readability, ensures endless methods remain a single line, and doesn’t cause exceptions when copying and pasting in IRB. To see what I mean, try copying and pasting the multi-line endless method above in IRB while the second example, using a normal block, will not error.

Related to Redundant Naming is the misuse of method parameters. The pattern you want to follow when defining method parameters is (listed in order of precedence):

💡 Read the Method Parameters And Arguments article to learn more.

Consider the following API client:

Notice both url and http are required keyword parameters which means we can’t easily construct a new client via Client.new which makes obtaining an instance of this object much harder. Each time we need an instance of this client, we’d have to type the following:

That’s overly verbose for little gain. Here’s an alternative approach that provides an improved developer experience:

Notice url is a positional parameter with a safe default while http is keyword parameter with a safe default. The distinction is subtle but powerful. Consider the following usage:

Due to the nature of an API client always needing to interface with an URL, you can avoid stating the obvious by making url a positional instead of keyword parameter. On the flip side, http needs to be a keyword parameter because it’s not entirely intuitive the second parameter is meant for injecting a different HTTP handler. In both cases, the positional and keyword parameter are optional which is a nice win in terms of usability without sacrificing readability.

Ruby has always allowed objects to be be monkey patched. Example:

In the above, we monkey patch the String class by opening it to add new behavior. Unfortunately, this new behavior now applies to all strings within the application that need to split themselves. Here’s the result of this change (truncated for brevity):

With the above example, we at least have a stack dump, despite not being shown, to trace back to where the monkey patch was introduced. What if the change was more subtle?

Upon using the above monkey patch, we see the following output:

Unfortunately, String#size always answers 13 now. Imagine if this code wasn’t in our application but was loaded from a gem dependency or — worse — indirectly via a gem’s own dependency. Beyond the struggle of identifying the root cause, the above also breaks expected behavior understood by all Ruby engineers, leading to time lost debugging confusing behavior not seen before.

All of the above leads to the following problems that will multiply and/or compound upon themselves in problematic ways:

Here’s how you can avoid monkey patching altogether:

Ruby has no limitation with defining multiple objects per file, as shown in the following:

There are several disadvantages to this lack of limitation:

Rather than multiple objects per file, a better solution would be to define each object in a separate file, like so:

Organizing one object per file helps encourage a consistent structure and reduces the strain of finding the associated file with the implementation you are looking for.

Multiple inheritance — or mixins — are a bad idea that are often abused. In the worst cases, they are used to extract common functionality from multiple objects as a way to share methods or DRY common functionality while not solving the problem of proper encapsulation at all. What you want to reach for is SOLID design and/or a more functional approach via the Command Pattern. One illustrative example of how bad this can get can be found in this article on A Kautionary Tale About Mixins. Again, stick to using the Single Responsibility Principle and Dependency Injection from SOLID and you’ll be much better off.

You can nest classes within each other and still be able to reference them anywhere in your application without fear of being scoped only to the parent namespace. This behavior is very different from languages, like Java for example, where an inner class is scoped to the outer class only. Here’s an example:

A module is similar to using a class:

In both cases above, the difference is between Outer being defined as either a class or a module. Both are acceptable and both are constants that give structure to your code.

The problem with nested classes arises when you truly want to use modules to organize your code and stumble upon some random nested class in your code base that has the same name as your module. This can be frustrating from an organization and refactoring standpoint since Ruby code is typically organized in modules. Here’s an example, along with an associated error, in which we attempt use a module without realizing a class of the same name existed:

For this reason alone, it’s better to avoid nesting your classes and use module for organizing your code, reserving class for your actual implementation.

A nonclass is a class with methods which have no state, behavior, or any relation to the class in which the methods were defined. Consider the following:

There are a several issues with the above implementation:

To correct the above, ensure the implementation is less brittle by making it more flexible through dependency injection:

With the above, the #call method has more relevance due to depending on the injected client. Even better, you can swap out the HTTP client implementation with any object that responds to #get and answers a response with a #status giving you more flexibility in how you might ping a remote server to check its status.

These were introduced in Ruby 2.7.0. Here’s a simple example:

To improve readability, you could write it this way:

While this solution requires more typing, good variable names help convey meaning and serve as a form of documentation. In this case, we’re not only printing names of people but we can see these are fictional characters. The value of this cannot be understated, especially if you were to iterate all enumerables using numbered parameters throughout your entire codebase. The use of _1, _2, _3, etc. would get monotonous quickly and make it hard to maintain context of each code block.

Nested blocks aren’t supported either because the following fails:

Similarly, you can’t use _1 as a variable name — not that you’d want to anyway. Example:

Focus on readability. Your fellow colleagues and future self will thank you.

While the original intent of adding comments to your code is well meaning, you want to avoid adding them since they tend to become stale, misleading, and cause misdirection when reading or debugging code. Instead, focus on refactoring your code so the code itself is self-describing or educate your team if they don’t understand certain concepts, patterns, and/or paradigms. To explain further, consider the following code comments:

All of the above examples read as if Captian Obvious wrote them. You could also be thinking: "Hey, wait, I don’t know what #tap, argument forwarding, or _method_ is so I need these comments!". Again, no you don’t. Ruby is a powerful language and just because you’ve not used certain aspects of the language doesn’t mean you should add comments to explain the code. All you probably need is a pointer to other examples within the code base or documentation to get up to speed. Once empowered with this new knowledge, you can then teach these techniques to other less experienced colleagues. This allows the team to keep leveling up while avoiding unnecessary and redundant documentation.

There are times where code comments are warranted, though. For example:

All of the above comments are valuable because they provide information that isn’t obvious and provide pointers on how to use or enhance the code further. In the case of the TODO and FIX comments, while not something you want to leave around for long periods of time, they do provide next actions for further code cleanup.

In summary, be judicious with your use of code comments, focus on self-describing code, and spread your knowledge across the team so everyone keeps leveling up.

Private and protected methods communicate the following in object design:

While the following is a contrived example — and would apply to protected methods too — notice how private clearly delineates between the objects’s public versus private API:

While you can use BasicObject#__send__ to message the #delimiter or #split private methods, you should avoid doing this for all of the reasons mentioned above. This includes testing a private or protected method. To emphasize further, avoid the following:

Naming objects, methods, parameters, etc. can be a difficult task when implementing code. In addition to using descriptive and intuitive names, you’ll want to ensure you don’t repeat terminology either. Take the following, for example:

Notice how the above example violates all of the following:

As you have probably concluded by now, the design of the namespace, object, methods, and related parameters is too verbose. There is no need to hit the reader over the head with redundant terminology. Instead we can simplify the above by leveraging the power of the namespaces in which the implementation is defined. Here’s a better way to write the above without sacrificing usability or readability:

Notice how the above eliminates all of the previous redundant terminology and greatly decreases the verbosity and noise within the implementation. Not only do we have a short and concise namespace for which to add and organize future objects but we also have query objects and can be constructed to answer scopes which might be chain-able by downstream objects. 🎉

A rude mutation occurs when you pass a value and mutate it as a side effect. Consider the following situation:

What’s surprising with the above is your message was mutated into a transformed result without any inclination it’d do this. One convention is to have a #yellize! method which indicates that there are side effects when sending the #yellize! message (i.e. mutation or exception). Using a bang-suffixed method is definitely one way to solve this problem but I’d want to ask is: Do you need the mutation in the first place? Don’t get me wrong, mutations can improve performance in certian situations but shouldn’t be the first thing you reach for. In that case, we could rewrite the implementation to be kinder to fellow engineers as follows:

The above is better because there are no surprising side effects. We see our message remains unmolested and we still get a new, but transformed string, we can use for further processing. Should you need more examples of rude mutations, you should read Tim Riley’s Salubrious Ruby on this subject.

Primitives are objects like String, Array, Hash, etc. It can be tempting to implement an object by subclassing one of these primitives and adding your own custom behavior. For example, let’s make a subclass of Array:

Notice how the Example instances start out reasonable enough but then take a surprising turn. This is because core primitives are implemented in C for performance reasons where the return values of several methods, like #+, are hard coded to answer the super type. This is why we get an Array instead of Example. This can lead to subtle and surprising behavior. Even structs don’t want to be subclassed.

You can avoid hard to debug behavior, like this, by using composition instead of inheritance:

With the above, we get all the benefits of Enumerable — which is generally what you want — by implementing a single method: #each. Delegation by extending Forwardable, for example, is another viable option.

Even the object size is reduced:

That’s a savings of 82 methods you most likely don’t need either. So, yeah, save yourself some heartache, use composition, and keep your objects simple.

May the above improve your code quality and make you a better engineer!