Tuesday, December 22, 2009

Shall Will Should Must May

SHALL WILL SHOULD MUST MAY

You see these terms in software requirements documents all the time. There is even an RFC that defines them. Unfortunately, RFC 9119 is poor practical advice.


Let's set the stage by focusing on the real world. The purpose of a real requirements document is to communicate a common understanding between two or more parties regarding some kind of functional contract. You write down what you want me to do and I'll do exactly what you say. Usually I'll expect you to pay me for the work. I'd like to do as little work as possible and you'd like to pay as little money as possible. This arrangement is very common when negotiating contract work and invariably the relationship degenerates to "the least effort for the least cost".

With that in mind, let's consider the RFC definitions.
1. MUST - This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
I draw a clear distinction between MUST and SHALL. I use the word MUST to state a design constraint such as, "all source code MUST be written in Java". There's no functional test I can apply to confirm that Java was used as opposed to C++ but for whatever reason, I might insist on Java. It is a design constraint, it is not a functional requirement.

I use the word SHALL to state a functional requirement such as, "the user interface shall be responsive". That's a poorly worded requirement but it is clearly different from a design constraint. I find it odd that RFC 9119 doesn't explicitly define the word SHALL which is probably the most commonly used word in requirements documents.

RFC 9119 also leaves WILL undefined. In the English language, the words SHALL and WILL are interchangable and their use seems to fall in/out of favor over generations. Typically, one word is viewed as a stronger form of the other but Websters says there's no clear hierarchy.

I take a more formal approach. Statements using the word WILL describe how the product is expected to be used or how it may interact with external systems. These statements are included for clarity and do not directly impose testable requirements for the product. For example, "the user will enter a password". In this case, the designer can expect a password will be entered but this is not a system requirement. The system might require password entry but clearly can't force the user to type anything. Given my definition of SHALL, it makes no sense to say, "the user shall enter a password".
2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the definition is an absolute prohibition of the specification.
Again, same thing here. MUST NOT is for design constraints. SHALL NOT is for requirements. However, it is worth noting that SHALL NOT statements raise instant suspicions. Typically they are untestable. Such as, "the system shall not crash".
3. 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.
Statements using the word should describe design objectives that are not directly testable. These statements provide guidance to the development team but do not translate into testable requirements for the product. For example, "it should be easy to change the delay". The designers can expect that at some point late in the development process, I will come back and require a different value for the delay. It better not be hard-coded all over the place. It would be best if there were a global variable that's easy to adjust. The word SHOULD is kind of a weaker version of the word MUST.
4. 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.
Again, this is similar to SHOULD. It is interesting that RFC 9119 defines MUST NOT, SHOULD NOT but leaves out MAY NOT.
5. MAY - This word, or the adjective "OPTIONAL", mean that an item is truly optional.
As a practical matter, I don't believe in optional requirements. It just doesn't make sense in the real world. The purpose of a requirements document is to communicate a common understanding between two or more parties regarding some kind of functional contract. You write down what you want me to do and I'll do exactly what you say. Usually I'll expect you to pay me for the work. I'd like to do as little work as possible and you'd like to pay as little money as possible. Now tell me, how do optional requirements fit into this arrangement?

If you tell me something is optional, then I'm not going to do it. I have been on plenty of projects where I argued with management that we need to implement this or that optional requirement. They never went for it. To them, "optional" equals "not required". You might as well have just left it out of the document. You just wasted your time writing it and wasted my time reading it.

I use the word MAY to indicate design decisions that are not important to me. Usually I provide the designers some choices. For example, "items may appear alphabetically or randomly". In other words, the system might be retrieving items from a database and the database might provide items alphabetically or randomly. I don't care how they are listed. Don't go out of your way to alphabetize them or randomize them. Either implementation is acceptable.

No comments:

Post a Comment