& - rspec

I've written previously (1, 2) about grammatical tense and mood in commit messages and docstrings. The point is that many hands advise avoiding a past-tense description in these messages in favor of a command, in the imperative mood that in English is often indistinguishable from the infinitive and the present tense. So they prefer

add ng-cloak to <body>

added ng-cloak to <body>

and to the even more freely composed content that is common in these messages.

I find something different but still grammatically self-conscious in the behavior prescribed for a number of development frameworks, where “behavior-driven development” is an important paradigm that prescribes modeling development in a linguistically natural way. Below are three examples.

RSpec, a development framework for Ruby, features a describe keyword to define methods. Within a describe-block each “expectation”, meaning prescribed behavior, is stated as a string in the present tense. The interesting twist is that this string is introduced by the pronoun it as a keyword, so that keyword and string together produce a descriptive sentence as the “expectation”. Here is an example from an exposition in Methods & Tools (Spring, 2011):

describe UsersController do

  describe '#create' do
  ...

    it 'creates a new user' do
    User.count.should == @count + 1
    end

    it 'sets a flash message' do
    flash[:notice].should be
    end

    it "redirects to the new user's profile" do
    response.should redirect_to(user_path(assigns(:user)))
    end
  end

end

See that describe is followed by a noun as object (UsersController, '#create'), while it is followed by a predicate, with a third-person singular verb, to make a complete present-tense sentence in the indicative mood.

The Methods & Tools write-up is careful to point out that the “expectation” should be a present-tense description, not a command or a grammatically explicit expectation:

Don’t begin example names with the word "should". It is redundant and results in hard to read spec output. Instead write examples by starting with a present tense verb that describes the behavior.

A descriptive “expectation” made up of it followed by a string is also used in the JavaScript framework Jasmine. But the Jasmine v. 2.0.0 documentation doesn’t observe the grammatical rigor of the RSpec examples:

A spec contains one or more expectations that test the state of the code. An expectation in Jasmine is an assertion that is either true or false.

Some examples from the same source show linguistic mismatch between describe and it and what follows them:

describe("A suite is just a function", function() {
  var a;

  it("and so is a spec", function() {
    a = true;

    expect(a).toBe(true);
  });
});

describe("The 'toBe' matcher compares with ===", function() {

  it("and has a positive case", function() {
    expect(true).toBe(true);
  });

  it("and can have a negative case", function() {
    expect(false).not.toBe(true);
  });
});

Here “and” prevents the expectation-string from forming a grammatical sentence with “it”. Reading the AngularJS documentation, however, I find that most examples there do form a grammatical sentence with it, though not avoiding “should” as prescribed for RSpec:

it('should remove the template directive and css class', function() {
  expect($('#template1').getAttribute('ng-cloak')).
    toBeNull();
  expect($('#template2').getAttribute('ng-cloak')).
    toBeNull();
});

The development framework JBehave also uses an explicit “behavior-driven” narrative

Given a precondition

When a negative event occurs

Then the outcome should be captured

in which the precondition is typically described using a noun, the when-clause as a present-indicative sentence, and the then-clause as an expectation with “should”. Here is an example from the v. 3.9.3 documentation:

public class TraderSteps {

    private Stock stock;

    @Given("a stock of symbol $symbol and a threshold of $threshold")
    public void aStock(String symbol, double threshold) {
        stock = new Stock(symbol, threshold);
    }

    @When("the stock is traded at $price")
    public void theStockIsTradedAt(double price) {
        stock.tradeAt(price);
    }

    @Then("the alert status should be $status")
    public void theAlertStatusShouldBe(String status) {
        ensureThat(stock.getStatus().name(), equalTo(status));
    }

}

[end]

Comments are enabled.