The language of specifications
As I’ve started working more and more with RSpec, I have found myself falling into a pattern of language use in my specifications, and that is one that mirrors the general language of RFCs. That language is best spelled out by Scott Bradner in RFC 2119, written in in 1997, but just as applicable today. It has the following definitions (paraphrased):
- MUST—This word, or the terms “REQUIRED” or “SHALL”, mean that the definition is an absolute requirement of the specification.
- MUST NOT—This phrase, or the phrase “SHALL NOT”, mean that the definition is an absolute prohibition of the specification.
- SHOULD—This word, or the adjective “RECOMMENDED”, mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
- SHOULD NOT—This phrase, or the phrase “NOT RECOMMENDED” mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
- MAY—This word, or the adjective “OPTIONAL”, mean that an item is truly optional. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option must be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)
Right now, I struggle with my use of the language and the framework, as I do not believe that should and should not have any place in the expression of specifications for a software implementation. Instead, I think that must and must not are the only options that actually are appropriate. These parallel the RSpec use of
shouldandshould_not, however the semantic differences bother me. The use of may can be appropriate in the English specification, but the concrete instantiation of the requirements must be exacting.For example, here is what I have as an idea for the representation of a standard (i.e. RFC that has become an Internet standard) as a ActiveRecord model. This is not the Ruby code, but the structure:
- A new Standard
- must have a governing organization (organization)
- must have a name (name)
- may have a number assigned (number)
- may have an issuance date (issued_on)
- may have revision information (revision)
- may have additional information attached (note)
I need to rip apart the RSpec implementation to see if it makes sense to just add
mustandmust_not_to the DSL.These are just some thoughts on how the language of specifications should work. To me, the RFC model and vocabulary has been exceptionally effective for years, and there is no reason to change the semantic structure. I go back and forth as to whether the keywords mentioned above should even be used in ALL CAPS in the English description, as they are in RFCs, or whether it’s simply acceptable to leave them in lower case.
This entry was posted at 11:56 pm on 27 October 2006 and is filed under Ruby. You can follow any responses to this entry through the post-specific RSS 2.0 feed.
There has been a lot of debate and thinking among BDDers to figure out what the most appropriate language is.
As repeated in countless other places, TDD is not abut testing. At least BDD is not. It is about design.
I think that using the word “should” in the process of designing code with RSpec keeps the programmer in a more exploratory and critical mindset than whith the moe dogmatic “must”.
Maintaining and evolving software also means maintaining specs, and this is a lot like gardening. The specs have to be trimmed and watered regularly, and sometimes they die – because they’re old.
This is a good thing. It is a sign of a software system that is alive and adapting to external forces.
Having specs that say “should” supports this kind of evolution, because it’s easier to ask the critical question: “Should it really?” and then perhaps end up changing or even deleting the spec.
If the spec said “must” people would be more hesitant to change the spec, which is actually bad – it’s the opposite of embracing change: rejecting change.
I believe that the concept of up-front and rigid requirements specifications only works in very few domains in computer science. I have never worked in an environment where requirements don’t change.
This is why I am more in favour of “should” than “must” in most cases. It may be a different case with specifications of protocols – they are much more rigid and can’t change as easily. But very few people write protocols.
Aslak, I see what you’re trying to get at, and I do agree that language is critical to influencing how people think about problems. In this situation, I’m just a bit concerned that should can represent a relatively weak encouragement to compliance. I suppose this is from my days working on protocols. The fact that the discussion is taking place is indicative of a healthy environment, however.
I think it’s also important to differentiate between what the specification wording says and what the testing does. Either that or we end up writing multiple sets of tests that duplicate 95% other than stringency. My point is that the
shouldmethod trickery has no tolerance (except in one case) for deviation, why should the language?Both comments and pings are currently closed.
The Precision of Specification/Requirements Language…
Chris Petrilli provides some excellent commentary on language and phrases used in specification and requirements documents. Over the course of my career producing specifications, requirements documents, project charters, etc. I have come to favor very …