Class variables behave a lot like global variables except they are scoped within their own class hierarchy rather than globally. 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, in 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:

You might be tempted to add behavior when initializing an object but this should be avoided for the following reasons:

Example:

As you can see, use of .parse provides a clean way to define, and self describe, behavior for the splitting of the body into individual lines without having to complicate initialization of the object.

Other methods like .for or .with are also great alternatives that allow you to keep object initialization simple so transformation behavior — the ability to take data in one format and convert it into a format that your initializer will understand — can remain isolated.

There is a way to dynamically namespace a class without wrapping the class in a module first. Example:

There are several reasons why this should be avoided:

A flat module structure looks like this:

Notice when printing the module structure at point of call we get a single element array: One::Two::Three. In contrast to the above, here’s the result when using 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, and provides a unique constant for each level of the hierarchy for relative reference and lookup. Nested modules allow you to avoid needless implementation construction and unexpected NameError errors. Nested modules also allow Ruby LSP, fuzzy typing, and other tooling that rely on nested namespaces to work properly.

💡 To prevent flat modules showing up in your code base, ensure the RuboCop Style/ClassAndModuleChildren cop is enabled which defaults to being enabled and enforces nested modules.

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.

Kernel.open provides a quick way to open a file or URL but introduces a security vulnerability by allowing arbitrary command execution when given a string (which could be anything). Use IO.popen or URI.open, instead, to avoid this vulnerability and keep your code secure. More information can be found in this Ruby Issue.

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 the method, 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 point 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:

Endless methods were introduced in Ruby 3.0.0 and are, generally, meant to be used as single expressions, not as single lines (more on this shortly). That said, there is a lot of value in keeping your endless methods simple via a single line only. For example, while valid syntax, don’t use endless methods for multi-line message chains:

Instead, use a normal method if multiple lines are necessary:

Even better — if an endless method can fit on a single line within RuboCop limits — then use the single line:

This improves readability and ensures endless methods remain a single line.

As alluded to earlier, the following is valid single expression endless method syntax (despite spanning multiple lines):

The above is valid syntax because end completes the expression. At the moment, I wouldn’t recommend using this syntax because tools like Caliber (RuboCop) don’t fully support this style. This also violates keeping the expression to a single line which is the greatest value endless methods provide.

If we focus on endless methods as single lines, make sure to keep them spaced:

As with normal methods, keeping your endless methods spaced allows for breathability/readability in your code. Along these lines, avoid assignment alignment:

You wouldn’t do this with standard methods, so avoid doing this with endless methods. This also simplifies refactoring an endless method to a standard method if desired (and visa versa).

Finally, avoid endless methods for initialization and memoization methods because the multiple equals is awkward to read:

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.

The primary purpose of a ternary is for short expressions, not control flow. Using ternaries for control flow is bad because the branching logic can be subtle to detect when quickly scanning code with only the ? and : to delimit branch logic. Consider the following:

In addition to avoiding control flow, you never want to span ternaries across multiple lines. If used, they should always be short one-liners that are quick to read, debug, and maintain. Anything more complicated than a one-liner means you need to expand the ternary into a multi-line if…​else…​end or case…​end expression. This includes not modifying existing ternaries with additional functionality.

In rare/limited situations, ternaries can be used for control flow if extremely short and clean. Example:

Again, strive to avoid using ternaries for control flow if you can.

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 — specifically Single Responsibility Principle and Dependency Inversion Principle — and/or a more functional approach via the Command Pattern.

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. Here’s an example:

A module is similar to using a class:

In both cases, 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 typical use case for an inner class is because you need a private implementation and this is done using private_constant, like so:

Here we get an error, which is what we want because the Inner class should only be accessed by the Outer class. This is the best use case for inner classes.

Unfortunately, the problem most seen with nested classes arises when you want to use modules to organize your code and stumble upon a random nested class in your code base that has the same name as your module. This can be frustrating from an organizational and refactoring standpoint since code is best 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 exists:

Worse — and more confusing — is when you nest modules within classes:

For this reason alone, it’s best to avoid nesting your classes and use module while reserving class for your actual implementation (unless needing to use a private inner class as stated earlier).

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.

Numbered parameters were introduced in Ruby 2.7.0. Example:

To improve readability, you can use a descriptive premature instead:

While this solution requires more typing, good parameter 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.

As of Ruby 3.4.0, you could alter the above to use it instead. Example:

This avoids the use of numbered parameters and reduces type without sacrificing too much readability. Use of it is definitely a step up from numbered parameters. As useful as it is there are times where it can be a hinderance such as when piping/chaining multiple messages together via #then and/or #tap because you might want a distinct parameter to clarify each step.

Returning to numbered parameters, 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:

When in doubt, choose readability over convenience because your 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:

What’s most important about private and protected methods is that they are meant for internal use only. They can change and be refactored all without breaking the public interface of your objects.

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

The above allows you to refactor, change the method signature, and rename the method entirely all without breaking your public Object API (i.e. #call). The same applies to protected methods with the only caveat that might have to refactor your subclasses too.

Sometimes people like to add @api private or @api protected code comments above their methods (most commonly found with YARD). Example:

Please avoid this for several reasons:

Finally, avoid using BasicObject#\__send__ to message private methods like #delimiter or #split as implemented above. This includes testing private or protected methods. The reasons are:

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 certain 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.

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.

When implementing global configurations/settings, they can be hard to test because you can’t reset or temporarily alter them. Example:

With the above, Demo.settings is permanently altered. To avoid this situation, allow your settings to be temporarily altered. Example:

By providing a block, you can temporarily use different settings for testing purposes without altering the original settings. What’s important, is the original settings are restored after the block exists allowing you to temporarily test different scenarios with minimal effort.

💡 If .as isn’t to your liking, using .isolate or .with_settings are good alternatives.

You’ve learned a lot of patterns to avoid. Tools like RuboCop, Reek, and others can catch a lot of these mistakes but not all. Armed with this knowledge, you can avoid these mistakes and save youself time.