You already know how to use modules in Ruby, but are you abusing them? In this post, we\u2019ll take a look at different ways to program with modules and why they may or may not be a great idea.<\/p>\n
Modules give you an easy way to namespace the rest of your code. For example, when you generate a new gem:<\/p>\n
$ bundle gem foo_bar_fighters<\/pre>\nYou get a default file with a module in it:<\/p>\n
$ cat foo_bar_fighters\/lib\/foo_bar_fighters.rb\r\nrequire "foo_bar_fighters\/version"\r\n\r\nmodule FooBarFighters\r\n # Your code goes here...\r\nend<\/pre>\nNow if you make a new class, you can put it in this
FooBarFighters<\/code> namespace:<\/p>\nmodule FooBarFighters\r\n class Song\r\n end\r\nend<\/pre>\nNow if you end up using another gem with a
Song<\/code> class, you can distinguish between the two by usingFooBarFighters::Song.new<\/code>.<\/p>\nIs this a good or a bad use of a module?<\/p>\n
Since it\u2019s auto generated by Bundler<\/a>, you can bet that using a module as a namespace is a good idea. Modules used this way allow any gem or project to use any class name that they desire without risk of cross contamination.<\/p>\n
That being said, if you have a very common name, like
FooBarFighters::File<\/code>, be careful; it\u2019s not always clear if you\u2019ll get yourFile<\/code> constant or Ruby\u2019s built-in constant. It\u2019s best practice to not duplicate core class names even if they\u2019re in a namespace. If you do have to, you can use the full constantFooBarFighters::File<\/code> for your constant and::File<\/code> (with the::<\/code> in front) for Ruby\u2019s built-in constant.<\/p>\nMethod Sharing<\/h2>\n
You can put methods into a module and then \u201cmix\u201d (i.e.<\/em>, include) them into a class.<\/p>\n
module Quack\r\n def say\r\n puts "quack"\r\n end\r\nend\r\n\r\nclass WaterFowl\r\n include Quack\r\nend\r\n\r\nWaterFowl.new.say\r\n# => "quack"<\/pre>\nIs this good or bad module use?<\/p>\n
This simple example is fine. However, there\u2019s no real reason for the module. It would be simpler and there would be less code if we put that method right inside of the
WaterFowl<\/code> class.<\/p>\nclass WaterFowl\r\n def say\r\n puts "quack"\r\n end\r\nend\r\n\r\nWaterFowl.new.say\r\n# => "quack"<\/pre>\nSince the module makes it more complicated, it\u2019s bad, right? Well, let\u2019s look at two separate examples from one of my projects: Wicked<\/a>.<\/p>\n
Sharing Behavior Through Modules<\/h2>\n
Wicked<\/a> is a gem for building \u201cstep by step\u201d wizard style controllers. It is a module, and you use use it by including it in your controller:<\/p>\n
class AfterSignupController < ApplicationController\r\n include Wicked::Wizard\r\n\r\n # ...\r\nend<\/pre>\n<\/p>\n
Note the namespace, yay!<\/p>\n
<\/i> <\/p>\n
It makes sense for Wicked to contain methods that are mixed into a controller since it can be mixed into multiple controllers.<\/p>\n
More than just methods though, the
Wicked::Wizard<\/code> module contains a set of behaviors that we want to share. When a user clicks on a specific link, we want them to go to the next page in the wizard flow. This is a good use of sharing methods via a module. In this case, the interface is provided by the module.<\/p>\nA benefit of this approach is that multiple interfaces can be layered on the same class. Originally, when I made Wicked, the interface was provided by a class that you had to inherit from.<\/p>\n
class AfterSignupController < Wicked::WizardController\r\n # ...\r\nend<\/pre>\nThis was not so great since it limits the ability to inherit from other custom classes (because Ruby only supports single inheritance). By putting our behavior in a module, we allow for a kind of multiple inheritance:<\/p>\n
class AfterSignupController\r\n include Wicked::Wizard\r\n include SetAdmin\r\n include MailAfterSuccessfulCreate\r\n include FooBarFighters::MyHero\r\n # ...\r\nend<\/pre>\nModule Method Extraction<\/h2>\n
Another use of splitting out methods can be seen in the Sprockets gem<\/a>, which I currently maintain. Sprockets split up lots of behavior into modules; here\u2019s a taste of a few of the modules:<\/p>\n
\n
- Sprockets::HTTPUtils<\/li>\n
- Sprockets::Mime<\/li>\n
- Sprockets::Server<\/li>\n
- Sprockets::Resolve<\/li>\n
- Sprockets::Loader<\/li>\n
- Sprockets::Bower <\/li>\n
- Sprockets::PathUtils<\/li>\n
- Sprockets::PathDependencyUtils<\/li>\n
- Sprockets::PathDigestUtils<\/li>\n
- Sprockets::DigestUtils <\/li>\n
- Sprockets::SourceMapUtils<\/li>\n
- Sprockets::UriUtils<\/li>\n<\/ul>\n
Each of these modules eventually makes its way to the class
Sprockets::Environment<\/code>, which is wrapped bySprockets::CachedEnvironment<\/code>. When you instantiate the object, it has 105 different methods. People call classes like this \u201cGod objects\u201d since they seem to be all powerful. TheSprockets::Environment<\/code> class definition in the source code is only 27 lines long without comments:<\/p>\nmodule Sprockets\r\n class Environment < Base\r\n def initialize(root = ".")\r\n initialize_configuration(Sprockets)\r\n self.root = root\r\n self.cache = Cache::MemoryStore.new\r\n yield self if block_given?\r\n end\r\n\r\n def cached\r\n CachedEnvironment.new(self)\r\n end\r\n alias_method :index, :cached\r\n\r\n def find_asset(*args)\r\n cached.find_asset(*args)\r\n end\r\n\r\n def find_all_linked_assets(*args, \u2588)\r\n cached.find_all_linked_assets(*args, \u2588)\r\n end\r\n\r\n def load(*args)\r\n cached.load(*args)\r\n end\r\n end\r\nend<\/pre>\nThis is bad. We only have five methods in this file. Where did the other 100 methods come from? Splitting out methods into modules just to mix them back into one God object doesn\u2019t reduce complexity; it makes it harder to reason about.<\/p>\n
I admit that at one point in time, \u201cconcerns\u201d \u2014 the practice of splitting out behavior for one class into many modules \u2014 was in vogue, and I too indulged in it. I even have a concerns folder in Wicked<\/a>. While it\u2019s fine to expose an interface of
Wicked::Wizard<\/code> via a module, the project (and docs) do not expect you to directly include these modules:<\/p>\n\n
Wicked::Controller::Concerns::Action<\/code><\/li>\nWicked::Controller::Concerns::Path<\/code> <\/li>\nWicked::Controller::Concerns::RenderRedirect<\/code><\/li>\nWicked::Controller::Concerns::Steps<\/code><\/li>\n<\/ul>\nThese are then all mixed into
Wicked::Wizard<\/code>. Splitting things up doesn\u2019t make things easier \u2014 it only means I can pretend that my files are small and that my main module doesn\u2019t introduce that many methods. Even though I wrote the code, I\u2019m constantly confused about which file holds what method. If anything, splitting out files in this way makes my job as a maintainer harder.<\/p>\nI previously wrote about reusing code with concerns<\/a> and legacy concerns in Rails<\/a>. If you haven\u2019t read them, don\u2019t. Extracting methods into a module to only turn around and
include<\/code> them is worse than pointless. It\u2019s actively damaging to the readability of your codebase.<\/p>\nGlobal Methods<\/h2>\n
When you put a method on a module directly (i.e.<\/em>, using
def self<\/code> orextend self<\/code>), then it becomes a global method. You can see this inSprockets::PathUtils.entries<\/code> method:<\/p>\nmodule Sprockets\r\n module PathUtils\r\n # ...\r\n\r\n def self.entries(path)\r\n if File.directory?(path)\r\n entries = Dir.entries(path, encoding: Encoding.default_internal)\r\n entries.reject! { |entry|\r\n entry.start_with?(".".freeze) ||\r\n (entry.start_with?("#".freeze) && entry.end_with?("#".freeze)) ||\r\n entry.end_with?("~".freeze)\r\n }\r\n entries.sort!\r\n entries\r\n else\r\n []\r\n end\r\n end\r\nend<\/pre>\n<\/p>\n
Code changed slightly for clarity of example.<\/p>\n
<\/i> <\/p>\n
This method finds all the files in a given directory and does not include any hidden files and returns a sorted array.<\/p>\n
You can use this method globally:<\/p>\n
Sprockets::PathUtils.entries("\/weezer\/blue-album")\r\n# => ["Buddy Holly", "Holiday", "In the Garage", "My Name Is Jonas No One Else", "Only in Dreams", "Say It Ain't So", "Surf Wax America", "The World Has Turned and Left Me Here", "Undone \u2013 The Sweater Song"]<\/pre>\nThe pros here are that the method can be used globally. This simple functionality can be tapped into by any piece of code without having to include the module. That means other code only has to know about the methods it needs instead of getting all the methods in the
PathUtils<\/code> module.<\/p>\nThe downside is that the method can be used globally; its scope isn\u2019t limited. If you need to change the behavior \u2014 let\u2019s say you need to return the array in reverse sorted order \u2014 you might break other code that you didn\u2019t even know was relying on this method.<\/p>\n
Is sharing methods globally by using methods directly on classes good or bad?<\/p>\n
Ideally you wouldn\u2019t need a global method, but sometimes it makes sense as an API. One example is
FileUtils<\/code>. I use this all the time to make directories:<\/p>\nrequire 'fileutils'\r\n\r\nFileUtils.mkdir_p("\/ruby\/is\/awesome\/lets\/make\/directories")<\/pre>\nThis is a global method, and
FileUtils<\/code> is a module:<\/p>\nputs FileUtils.class\r\n# => Module<\/pre>\nI\u2019ll say that using modules for global methods is better than for building God objects. How so? If you look at the code:<\/p>\n
def stat_digest(path, stat)\r\n if stat.directory?\r\n # If its a directive, digest the list of filenames\r\n digest_class.digest(\r\n self.entries(path) # <===================\r\n .join(','.freeze))<\/pre>\nI would prefer if it was more explicit:<\/p>\n
def stat_digest(path, stat)\r\n if stat.directory?\r\n # If its a directive, digest the list of filenames\r\n digest_class.digest(\r\n PathUtils.entries(path) # <===================\r\n .join(','.freeze))<\/pre>\nIn the second example, we know exactly where to look for our implementation (in the
PathUtils<\/code> module) since it\u2019s right in front of us. We also know that the method call isn\u2019t mutating anything that is not passed in. For example,PathUtils<\/code> could be mutating the path argument but nothing else. It doesn\u2019t have access to any of the rest of the current scope.<\/p>\nWe still haven\u2019t said if sharing global methods via modules is good or bad. If there is no way you can work around needing a global method, what are other options for exposing a method globally?<\/p>\n
You could define it in a top level context:<\/p>\n
$ irb\r\n> def nirvana\r\n puts "come as you are"\r\n end\r\n\r\n> class Foo\r\n def say\r\n nirvana\r\n end\r\n end\r\n\r\n> Foo.new.say\r\n# => "come as you are"<\/pre>\nYou could also \u201cmonkey patch\u201d it into
Object<\/code> orKernel<\/code>:<\/p>\nclass Object\r\n def nirvana\r\n puts "come as you are"\r\n end\r\nend\r\n\r\nclass Foo\r\n def say\r\n nirvana\r\n end\r\nend\r\nFoo.new.say\r\n# => "come as you are"<\/pre>\nWe can agree (hopefully) that both of these approaches are more surprising and more invasive to the end user than stashing our global methods in a module. We\u2019ll say that using modules for global methods is \u201cgood.\u201d<\/p>\n
Bad Modules Make for Good Objects<\/h2>\n
Many of the \u201cbad\u201d module practices (including my own) came from a somewhat limited understanding of object-oriented design.<\/p>\n
You may hear things like \u201cnever have a file longer than [some number] lines of code,\u201d which leads you to think that taking the existing methods, splitting them out into modules and including them is the quick fix. While it will give you shorter files, it also makes things worse. It kills readability and grepability.<\/p>\n
A well-written class can be a work of art, while most modules tend to be proverbial junk drawers. This isn\u2019t a post on OO design though, so I\u2019ll punt on that. If you want to know more, look up \u201crefactoring confreaks Ruby,\u201d and you\u2019ll find a ton of material. One notable book on the subject is Practical Object Oriented Design in Ruby<\/em><\/a> by Sandi Metz<\/a>.<\/p>\n
Modules are a valuable tool in your Ruby toolbox. But next time you reach for a module to solve a problem, ask yourself if it\u2019s a \u201cgood\u201d fit for the job. <\/p>\n
\n