Question

RSpec adds a “describe” method do the top-level namespace. However, instead of simply defining the method outside of any classes/modules, they do this:

# code from rspec-core/lib/rspec/core/dsl.rb 
module RSpec
  module Core
    # Adds the `describe` method to the top-level namespace.
    module DSL
      def describe(*args, &example_group_block)
        RSpec::Core::ExampleGroup.describe(*args, &example_group_block).register
      end
    end
  end
end

extend RSpec::Core::DSL
Module.send(:include, RSpec::Core::DSL)

What is the benefit of using this technique as opposed to simply defining describe outside any modules and classes? (From what I can tell, the DSL module isn’t used anywhere else in rspec-core.)

Answer 1

I made this change a few months ago so that describe is no longer added to every object in the system. If you defined it at the top level:

def describe(*args)
end

…then every object in the system would have a private describe method. RSpec does not own every object in the system and should not be adding describe willy-nilly to every object. We only want the describe method available in two scopes:

describe MyClass do
end

(at the top-level, off of the main object)

module MyModule
  describe MyClass do
  end
end

(off of any module, so you nest your describes in a module scope)

Putting it in a module makes it easy to extend onto the main object (to add it to only that object, and not every object) and include it in Module (to add it to all modules).