Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
I realize this is somewhat subjective, but I can't find a good case for one or the other :
it "should do something"
it "does something"
Proponents of the should style mention that it forces you to actually question what it is you are trying to achieve, while detractors find it just redundant.
Is there a consensus on this, or is it purely a matter of style ?
Welcome to Legal English.
Using "should" == "shall" == contractual obligation. It's a legalism. It doesn't lead to "questioning". It marks the sentence as a formal contractual obligation.
Using "would" == "will" == nice idea. It marks the sentence as an optional feature.
Questioning is part of facilitation, organization, helping, building trust. Not a consquence of word choice.
Using a bare verb without the modifier makes the sentence slightly harder to highlight as a formal requirement. And in the case of super-complex verbs, it can get a little dicey to figure out how to conjugate it.
Easy -- verbs like "to notify" or "to create".
The system notifies via email. (The verb "to notify" is conjugated "notifies" for "the system"--whatever that is.)
The system shall notify via email. ("to notify" becomes "shall notify" -- no conjugation. Very simple.)
Hard -- verb phrases like "to log in" or domain-specific verb phrases like "to extract, cleanse, transform, deduplicate and load" or a noun like "prospect" which has been verbed. The longer phrase which has several verbs buried in it is hard to conjugate: conjugate each verb? Or try to conjugate the long phrase as if it was a single word? Since any noun can be verbed in English, it's hard to know how to conjugate those made-up verbs.
The system extract, cleanse, transform, deduplicate and loads when the user clicks enter. (English trivially verbs any noun phrase.) Or is it extracts, cleanses, transforms, deduplicates and loads?
The system should extract, cleanse, transform, deduplicate and load when the user clicks enter. (The hideous phrase is left intact, no mystery about the verb conjugation.)
["What?" you say, "any noun can be verbed in English?". Yes. Any noun. I'm going to stonewall on that. I've often stonewalled on that. Even the specifications should stonewall on that.]
Purely a matter of stylistic preference. It boils down to asking, do you/your clients prefer to think about the system in present or future tense?
Qualifiers like "should" or "will" implies future tense, but this is soft and reads well enough when thinking in present tense. Lack of a qualifier definitely indicates present tense (i.e. right this moment).
I prefer using a qualifier because it reads passably well in both cases, whereas lack of qualifier reads a bit strangely during development when everything is future tense.
In any case, if you decide to use a qualifier I strongly recommend using "must" instead of "should". "Should" can be interpreted as being optional (despite S.Lott's assertion to the contrary), but "must" completely removes any ambiguity - must clearly means "not optional".
And because I can't yet comment (karma constraints), this is a response to S.Lott about Should/Shall vs. Would/Will: there's a lot of ambiguity about shall and will, even in legal contract writing. See this article for an explanation.
I am in favor of using third person, present tense without a qualifier.
My main argument is that: A test is a story.
A story consists of scenes. Each scene describes:
Example:
DESCRIBE:
getReceiptfunctionCONTEXT: receipt exists
IT: returns the receipt
Just like a good story, a good test is easy to read.
A story tells you what the program does, e.g.
On the other hand, using a qualifier (does not matter if it is "should" or "must") turns the test into a list of assertions, e.g.:
There is no continuous story: your mind is evaluating a list of assertions.
This is subjective, but reading natural language (a story) is simpler than reading a list of assertions.
In my opinion, you should always use 'should'.
Reasoning - with BDD, when you're writing the test, the software doesn't yet do what you want it to do, so saying it "does something" is false. It "should do something", and the tests will pass as long as it continues to do that something.
From behaviour-driven.org titled "GettingTheWordsRight":
In short, the words that we use to describe things influences the way in which we (and others) think about those things. This isn't just a simple question of being petty about semantics either, as certain words carry with them nuances that affect how we interpret the meaning of a phrase at both an intellectual and an emotional level. Our language is rich with descriptive words and phrases so it seems reasonable to use words that will clearly convey the intention of the elements that we wish to describe in code.
In the case of BDD, I'm personally who almost always uses the word should when naming tests, because its usage implies that while the intention is for a test to provide a certain result, other unexpected consequences may arise which will need to be dealt with if a test result is to be considered valid. You could perhaps use the words expect or must similarly, however these words imply a more imperative viewpoint such that the name of the test could be mistaken to mean "there is nothing wrong with the test, assume the implementation is messed up", whereas *should" implies that the test is likely to be correct, yet may need to be checked again for error if the test results don't seem to add up. I like this, because it influences your thinking such that you are encouraged to keep an open mind as you code, which is very important when you wish to avoid getting stuck as you attempt to debug your code and find yourself looking in the wrong place for errors because of an assumption.
I have however seen the near 'religious' application of the word should fail when it has been enforced as a prefix for test names, as it has forced the programmers involved to go through certain mental and linguistical gymnastics in order to provide a test name that was meaningful, and in such cases it has meant that the intention to get the words right does not meet its expectations, and the tests themselves become difficult to decipher as a result. When this sort of situation crops up, I would usually use the word should at any place within the test method name, to ensure the name conveys its method simply and clearly. I would certainly not however enforce a particular word usage if other words were equally appropriate within a given context. The trick however is to choose words that leave no room for argument about what something represents in code, and that provoke you into thinking about the things that your code is supposed to do without relying on mere implication.
