rubyspec

h1. Style Guide

Generally, "RSpec":http://rspec.rubyforge.org specs describe the expected behavior of code. While RSpec is fairly young, there are some conventions for writing specs. The RubySpecs cover a wide variety of components, so we have developed some pragmatic conventions to handle the various situations. As noted below, some conventions are more rigid than others.

These conventions apply to all specs. Existing specs that deviate from these conventions need to be fixed. Consistency is the principle that will almost always trump other conventions. Consistency aids understanding and readability. There are many thousands of lines of code in the spec files, so the value of consistency cannot be overstated.

The specs uniformly use @describe@ not @context@. The use of @it@ is preferred over @specify@ except in situations when the first word of the string is not a verb. The word "should" is unnecessary noise in the spec description strings and is not used. (The rationale is this: the spec string describes the expected behavior unconditionally. The code examples, on the other hand, set up an expectation that is tested with the call to the _should_ method. The code examples can violate the expectation, but the spec string does not. The value of the spec string is as clearly as possible describing the behavior. Including "should" in that description adds no value.)

Whenever possible, the spec strings should be written to conform to very basic English sentence structure: _subject + predicate_. The spec strings also uniformly use double-quotes, not single-quotes. The minimum number of words should be used to describe the behavior. Only make distinctions when they add significant value to understanding the behavior. This is explained further below. The general rule across all the specs is to use the least amount of detail to unambiguously describe behavior. Add to the detail conservatively. This is conceptually consistent with doing the simplest thing that could work.

h2. 1. Core and Standard Library

The specs for the Ruby core and standard libraries use one @describe@ block per method. For particularly complex methods, such as Array#[], more than one @describe@ block may be used according to the nature of arguments the method takes.

The @describe@ string should be "Constant.method" for class methods and "Constant#method" for instance methods. "Constant" is either a class or module name. For subclasses or submodules, the "Constant" name should be "Super::Sub". The @describe@ string should not include arguments to the methods unless absolutely necessary to describe the behavior of the method. Keep in mind that in Ruby duck-typing is a deeply embedded concept. Many methods will take any object that responds to a particular method or acts like an instance of a particular class.

  # This is correct

  describe "String#eql?" do

    it "returns true if other has the same length and content" do

      ...

    end

  end

  describe "Array#[]= with [index, count]" do

    it "returns non-array value if non-array value assigned" do

      ...

    end

  end

Contrast the _good_ example above with the one below. The following example deviates from the conventions for @describe@ strings and uses "should" and single-quotes for the descriptions.

  # This is NOT correct

  describe "String#eql?(string)" do

    it 'should return true if other has the same length and content' do

      ...

    end

  end

  describe 'Array#[]=(index, count)' do

    it 'returns non-array value if non-array value assigned' do

      ...

    end

  end

The vast majority of the spec files for the core library have already been created. To create template files for the standard library classes, refer to the "mkspec":/wiki/mspec/Mkspec documentation.

h3. 1.1 Utility Classes

Many spec code examples refer to a particular class. To prevent name clashes with these different class definitions across all the specs, the classes should be scoped to a module. The convention is as follows:

module ObjectSpecs

  class SomeClass

  end

end

The module is named after the class for which the specs are being written. So, for the specs for _Object_, the module name is ObjectSpecs.

These utility classes are also referred to as _fixtures_. In the directory for each class, there is also a @fixtures@ directory. Refer to the existing files for examples.

h3. 1.2 Aliased or Identical Methods

Ruby has a significant number of aliased methods. True aliases are identical methods, so the specs should be exactly the same for each aliased method. The following illustrates the convention for specs for aliased methods (or just otherwise identical interfaces.)

In @rubyspec/1.8/core/array/shared/collect.rb@

shared :array_collect do |cmd|

  describe "Array##{cmd}" do

    it "returns a copy of array with each element replaced by the value returned by block" do

      a = ['a', 'b', 'c', 'd']

      b = a.send(cmd) { |i| i + '!' }

      b.should == ["a!", "b!", "c!", "d!"]

    end

    it "does not return subclass instances" do

      MyArray[1, 2, 3].send(cmd) { |x| x + 1 }.class.should == Array

    end

  end

end

In @rubyspec/1.8/core/array/collect_spec.rb@

require File.dirname(__FILE__) + '/../../spec_helper'

require File.dirname(__FILE__) + '/shared/collect.rb'

describe "Array#collect" do

  it_behaves_like(:array_collect, :collect)

end

In @rubyspec/1.8/core/array/map_spec.rb@

require File.dirname(__FILE__) + '/../../spec_helper'

require File.dirname(__FILE__) + '/shared/collect.rb'

describe "Array#map" do

  it_behaves_like(:array_collect, :map)

end

Writing specs that use floating point values poses a problem because two values that look the same when rendered to a string may not actually be bitwise equal. Specs that compare floating point values should use @#should_be_close@ with the TOLERANCE constant.

h2. 2. Language

For the language specs, there is nothing as convenient or as concrete as a particular method to spec. Review the discussion of the "organization":/wiki/rubyspec/Organization of the language specs. The general conventions apply here: use simple English to describe the behavior of the _language entities_ and only add detail as needed. Use a single @describe@ block initially and add distinguishing @describe@ blocks as necessary. Use @it@ rather than @specify@ whenever possible.