It "should [action] ..." vs it with an active voice

Testing RSpec
1

I’d like to start gathering information/debating on the
advantages/disadvantages of using it “should …” vs other techniques.

Dan N. explained why we should use should:

I used to use it “should …” for the projects I was on, until I was
challenged by a fellow developer who started using it with an active
voice.
For example instead of:
it “should go to the park”
An active voice would be:
it “goes to the park”

After a few days of reluctance (or stubbornly hanging on to the rspec
“convention”), I eventually adopted and grown to love using the active
voice.

Here are the main reasons that I prefer an active voice because:

  • using it “should …” over and over renders should meaningless (I
    have grown this barely conscience aversion to the word ‘should’)
  • less less words are needed
  • the differentiating information of the ‘it’ statement is in the
    front, rather than hidden behind should (space to the left is at a
    premium)
  • it describes what the software will do and what it does (both from
    the Test Driven Design and Regression verification lifecycles of the
    test)
  • you still have a good “sentence template” that “should” provides
    (you have to make a coherent sentence)

So here it my initial stab. Lets discuss :slight_smile:

Thanks,
Brian

2

On Nov 12, 2007 11:39 AM, Brian T. [email protected] wrote:

  • you still have a good “sentence template” that “should” provides
    (you have to make a coherent sentence)

So here it my initial stab. Lets discuss :slight_smile:

I definitely agree that the active voice is nice in spec strings.

A coworker, when he first saw the use of ‘should’, said something
along the lines of “I thought you were writing specifications, not
recommendations.” I fumbled and tried to explain that away, but the
objection has stuck with me. I’ve also noticed on Rubinius’ spec style
guide that the use of should is discouraged:

http://rubinius.lighthouseapp.com/projects/5089/specs-style-guide

There are still some places that I use ‘should’, and if I’m working in
a project that tends to use it, I’ll stick with it. But in my own
work, I prefer ‘it has 4 entries’ to ‘it should have 4 entries’.
(Though, in the code, the use of ‘should’ to express the expectation,
does make sense, as the Rubinius page explains).

Thanks for bringing this up, I’d been thinking about it lately.

Kyle

3

On Nov 12, 2007 9:39 AM, Brian T. [email protected] wrote:

For example instead of:
have grown this barely conscience aversion to the word ‘should’)
So here it my initial stab. Lets discuss :slight_smile:

Thanks,
Brian

rspec-users mailing list
[email protected]
http://rubyforge.org/mailman/listinfo/rspec-users

At first glance I think this will be an awkward style for me to adopt.
It’ll take a bit to break out of my current mentality. That said, I
think it makes a lot of sense. I’m going to try it out this week, and
hopefully I’ll fall in love with it.

Pat

4

On Nov 12, 2007 1:51 PM, Kyle H. [email protected] wrote:

test)

  • you still have a good “sentence template” that “should” provides
    (you have to make a coherent sentence)

So here it my initial stab. Lets discuss :slight_smile:

I definitely agree that the active voice is nice in spec strings.

A coworker, when he first saw the use of ‘should’, said something
along the lines of “I thought you were writing specifications, not
recommendations.”

Unfortunately, as we tried to get away from the word “test” and all
the baggage it brings along with it, we landed on another word,
“specification,” which bears its own baggage.

In most cases, we are not writing specifications in the traditional
sense. Sure, we are specifying how our objects should behave, but that
notion changes daily as new requirements enter the system and we
mercilessly refactor. It’s not the same kind of “specification.”

I fumbled and tried to explain that away, but the
objection has stuck with me. I’ve also noticed on Rubinius’ spec style
guide that the use of should is discouraged:

Lighthouse - Beautifully Simple Issue Tracking

That rationale seems a bit arbitrary to me. Why should there be
anything different between the doc strings and the code in the
examples? They’re both talking about how the objects should behave.
Not how they do behave, but how we expect them to behave. The examples
can fail, in which case the objects are not behaving as they should,
nor are they behaving as the doc strings state that they unequivocally
are when you use imperative or active voice.

Secondly, while the Rubinius team is using RSpec (which is great) and
they are writing executable specifications (which is even greater!),
writing a complete specification for an existing language is not
really what BDD is all about. And so while they may be doing something
akin to BDD, or the “language specification flavor” of BDD, it is
really unrelated to the BDD process that the word “should” was chosen
to support.

The process I’m talking about is an iterative process. Not just
iterative in terms of developing the software, but in terms of
discovering requirements of the software as well. The idea is to be
able to respond to change, to check assumptions, and to constantly
redesign the system to align with the requirements as they are
understood to be right at that moment.

The Rubinius specs are a language specification. The team is not going
to learn during iteration 27 that String#eql should return true for
Strings that are the same except for one character. The spec is
actually a spec. It’ll take the CEO’s signature to change it.

All of this to say that I think “should” works well when what should
happen can (should???) change from time to time as we learn more about
the system.

There are still some places that I use ‘should’

What is the criteria for you? When would you choose “should” and when
would you choose active voice?

and if I’m working in
a project that tends to use it, I’ll stick with it. But in my own
work, I prefer ‘it has 4 entries’

But it DOESN’T have 4 entries when you write that example. Then it
does when you get the example to pass. But what if the example fails
later on? The example says “it has 4 entries”, but that is wrong. What
is correct in that context is that it “should have 4 entries,” but
doesn’t. And recognizing that gives you some flexibility to ask
yourself whether the object is wrong, or the example is wrong. That
was one of the motivating factors behind the choice of “should”, and I
personally find it quite compelling.

to ‘it should have 4 entries’.
(Though, in the code, the use of ‘should’ to express the expectation,
does make sense, as the Rubinius page explains).

Thanks for bringing this up, I’d been thinking about it lately.

Hear, hear! I have my not-so-subtle opinions about this, but I’m glad
to see the notion being challenged and look forward to other opinions.

Cheers,
David

5

On Nov 12, 2007 6:09 PM, Pat M. [email protected] wrote:

(btw, I think that because of that, specs != unit tests. They’re very
similar, but I’ll be so bold as to claim that there are no unit tests
in BDD)

To preempt any snarkiness… :slight_smile:

Of course there are no unit tests in BDD, because there are no tests
in BDD! What I really mean is that there is nothing in BDD which maps
directly to the traditional concept of “unit test.”

Pat

6

I’m going to flip some of your stuff around, and hopefully I arrive at a
point.

On Nov 12, 2007 5:22 PM, David C. [email protected] wrote:

yourself whether the object is wrong, or the example is wrong. That
was one of the motivating factors behind the choice of “should”, and I
personally find it quite compelling.

It probably doesn’t matter much. In fact, if you make an imperative
statement and the example fails, then the contradiction produces a
nasty, noisy, “LOOK AT ME! LOOK AT ME! SOMETHING IS BROKEN! FIX IT”
which is generally what you want with unit tests.

However…

discovering requirements of the software as well. The idea is to be
able to respond to change, to check assumptions, and to constantly
redesign the system to align with the requirements as they are
understood to be right at that moment.

The Rubinius specs are a language specification. The team is not going
to learn during iteration 27 that String#eql should return true for
Strings that are the same except for one character. The spec is
actually a spec. It’ll take the CEO’s signature to change it.

In BDD, the unit tests are not the final authority on how the system
should behave. I think this is a fundamental difference from
traditional TDD. If your specs are failing, that might suck, or it
might not. It doesn’t necessarily mean anything is broken. Stories
are the final authority and let you know when something is broken.
But our specs are just a tool to help us design, and sometimes they
are a bit more useful by helping us localize issues.

(btw, I think that because of that, specs != unit tests. They’re very
similar, but I’ll be so bold as to claim that there are no unit tests
in BDD)

So, in that sense, I think this ought to be the combination of
spec/story for the simple account withdrawal example:

Given my savings account balance is $100
And my cash account balance is $10
When I transfer $20
Then my savings account balance is $80
And my cash account balance is $30

(if you look at http://dannorth.net/2007/06/introducing-rbehave you’ll
see that he uses “should be” for the Then clauses)

describe Account do
before(:each) do
@savings = Account.new 100
@cash = Account.new 10
end

it “should transfer $20 to another account” do
@savings.transfer_to @cash, 20
@savings.balance.should == 80
end

it “accept a $20 transfer from another account” do
@savings.transfer_to @cash, 20
@cash.balance.should == 30
end
end

The description uses “should,” thus is gentle and fluid. If an
example fails, the developer can choose how to handle it however he
wants.

The story, on the other hand, must use imperative statements. If it
fails, the developer must either fix the code so it passes, or have a
conversation with a customer if he feels the requirements may have
changed.

I hope I didn’t muddle anything by using such a simple example. In
fact I’m sort of hoping that it gets the point across better…under
the hood, the description and spec have virtually identical
implementations. The difference is that the story is an authoritative
spec of how the system should behave, and the description has no
authority at all.

Pat

7

On 11/12/07, David C. [email protected] wrote:

From the belief that the customer is the ultimate authority on what it
means for the system to behave acceptably, and the fact that stories
are customer-facing and specs are developer-facing.

Pat

8

On Nov 12, 2007 9:03 PM, Pat M. [email protected] wrote:

means for the system to behave acceptably, and the fact that stories
are customer-facing and specs are developer-facing.

I totally agree that the customer is the authority - however, the
customer has just as much right to change her mind about a story as I
do about a spec! So why should stories be any more locked down than
specs?

9

On Nov 12, 2007 7:12 PM, David C. [email protected] wrote:

From the belief that the customer is the ultimate authority on what it
means for the system to behave acceptably, and the fact that stories
are customer-facing and specs are developer-facing.

I totally agree that the customer is the authority - however, the
customer has just as much right to change her mind about a story as I
do about a spec! So why should stories be any more locked down than
specs?

Stories represent a bridge between the customer’s and the developer’s
minds, a snapshot of the shared understanding at a given point in
time. They do not obviate the need for customer-developer
communication. A customer should be able to change her stories as
much as she wants, but all but the very simplest changes ought to spur
a discussion and reevaluation of assumptions.

Pat

10

On Nov 12, 2007 8:47 PM, Pat M. [email protected] wrote:

minds, a snapshot of the shared understanding at a given point in
time. They do not obviate the need for customer-developer
communication. A customer should be able to change her stories as
much as she wants, but all but the very simplest changes ought to spur
a discussion and reevaluation of assumptions.

Pat

Also, I don’t think this approach poses an obstacle to creative tools
like a Story Builder. If anything, I’d say it enhances those tools.
A customer can play with the tool and build various stories without
committing to anything, building stories and then tossing them away on
a whim. Then when she finds a few stories she likes - perhaps it’s
very valuable, or 80% of the steps are already done - she can bring
them up with the developer. That would allow the customer to take a
more active role in exploring potential stories, and make more
efficient use of direct customer-developer collaboration because less
time is wasted sifting through half-hearted stories.

Pat

11

On Nov 12, 2007 8:09 PM, Pat M. [email protected] wrote:

The difference is that the story is an authoritative
spec of how the system should behave, and the description has no
authority at all.

I don’t have that sense at all. Where do you get that from?

12

On Nov 12, 2007 10:56 PM, Pat M. [email protected] wrote:

I don’t have that sense at all. Where do you get that from?
Stories represent a bridge between the customer’s and the developer’s
like a Story Builder. If anything, I’d say it enhances those tools.
A customer can play with the tool and build various stories without
committing to anything, building stories and then tossing them away on
a whim. Then when she finds a few stories she likes - perhaps it’s
very valuable, or 80% of the steps are already done - she can bring
them up with the developer. That would allow the customer to take a
more active role in exploring potential stories, and make more
efficient use of direct customer-developer collaboration because less
time is wasted sifting through half-hearted stories.

More violent agreement! Although are we still talking about “should”?
I think that got lost somewhere.

13

On Nov 12, 2007 10:47 PM, Pat M. [email protected] wrote:

I don’t have that sense at all. Where do you get that from?
Stories represent a bridge between the customer’s and the developer’s
minds, a snapshot of the shared understanding at a given point in
time. They do not obviate the need for customer-developer
communication. A customer should be able to change her stories as
much as she wants, but all but the very simplest changes ought to spur
a discussion and reevaluation of assumptions.

We are in violent agreement!

But, as irony would have it, this agreement seems to lead us to
different conclusions. My thinking is that “should” actually works
well in stories for all the same reasons it works well in specs. You
seem to take that in a different direction, no?

14

On Nov 12, 2007 9:00 PM, David C. [email protected] wrote:

authority at all.
specs?
But, as irony would have it, this agreement seems to lead us to
different conclusions. My thinking is that “should” actually works
well in stories for all the same reasons it works well in specs. You
seem to take that in a different direction, no?

Right. I think that “should” leaves a lot of wiggle room. While I
believe that the customer should be allowed to change her stories, I
don’t think those changes should be finalized without a convo between
customer and developer. “should” allows you to make a judgment call
and move on, which is the flexibility you want in specs, whereas a
slightly more rigid structure makes it clear that new discussion is
required.

Pat

15

On Nov 12, 2007 9:01 PM, David C. [email protected] wrote:

authority at all.
specs?

More violent agreement! Although are we still talking about “should”?
I think that got lost somewhere.

No, I went down a separate path there. I figured that someone could
read my thoughts and ask, “But doesn’t that mean less flexibility for
the customer? She always has to strike up a convo with the developer”
to which the reply is “only when she needs to.”

Pat