Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

At least in the US, "will" has replaced "shall" in most every context, with the notable exception of the "legal shall". Shall is used instead of will in legal documents to indicate a sense of obligation or requirement; e.g. "the defendant shall vacate the premises by October 16".

In software, requirements documents and specification documents serve close to the same purpose as the aforementioned legal documents; does this mean shall should be used in a similar fashion as a result?

share|improve this question
add comment

migrated from programmers.stackexchange.com Oct 9 '12 at 13:18

This question came from our site for professional programmers interested in conceptual questions about software development.

6 Answers

Shall is still used in software documentation. It was a subject of discussion in my software engineering course and it's also present in field documentation.

An example can be found in the Joint Strike Fighter's C++ coding standard. In section 4.2 under Rules on page 11. It specifically defines the following:

4.2.1 Should, Will, and Shall Rules

There are three types of rules: should, will, and shall rules. Each rule contains either a “should”, “will” or a “shall” in bold letters indicating its type.

  • Should rules are advisory rules. They strongly suggest the recommended way of doing things.

  • Will rules are intended to be mandatory requirements. It is expected that they will be followed, but they do not require verification. They are limited to non-safety-critical requirements that cannot be easily verified (e.g., naming conventions).

  • Shall rules are mandatory requirements. They must be followed and they require verification (either automatic or manual).

So at the very least, within the last decade for government contract work, shall does have a great deal of force. I suspect it's still much the same in the private sector, though perhaps not nearly as strict in the case of projects not involving multi-billion dollar avionics.

share|improve this answer
    
+1. If "shall" has been strictly defined in your field, use it. If "shall" has not been strictly defined, e.g. you are working in a field where requirements gathering is informal, it might be best avoided. –  MarkJ Oct 9 '12 at 8:18
3  
Most of our requirements documents explicitly define terms, even if we are using them as defined in RFC 2119 or another standard document (which is also referenced/linked to). This is because different customers have different interpretations of these terms, and it makes it easy for everyone to always be on the same page. Regardless of how you use them, defining them is a Good Thing. –  Thomas Owens Oct 9 '12 at 10:19
    
+1, as a good example, but label me "not thrilled". Coding standards ideally are short and sweet, something you can convince every programmer on the team to read, to understand, to agree with, and to abide by. A coding standard that vies with the federal tax code in terms of complexity and length is not a good standard. Shall, shall not, nothing else. There are always waivers, even for the beast with a cyclomatic complexity greater than 500. –  David Hammen Oct 9 '12 at 11:20
add comment

RFC 2119 defines the meanings of various words used in specifications (such as other RFCs). It defines SHALL as a synonym of MUST. I think it's preferable to use MUST, as it conveys the meaning more clearly.

share|improve this answer
add comment

Option 1: use RFC 2119

According to RFC 2119:

  1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.

This is also the most current use of the word "shall" from what I've seen in the requirements.

Option 2: use present tense

If the requirements are mostly mandatory, you may also want to formulate the requirements in present tense, without "must", "shall" or other keywords. Example:

The undo history is preserved when the application is closed.

The requirement clearly states, by its present tense, that the requirement is mandatory. The history should be preserved, and if it's not, the software fails to pass this requirement.

Such way of writing the requirements allows them to be slightly more readable, without losing their mandatory property.

Option 3: use your own conventions

Note that you may define your own terminology in the documents you write. That's why most documentation starts by defining the terms, including "must", "can", etc. For example, HTTP specification contains such section: 1.2 Requirements.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [34].

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements for the protocols it implements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements for its protocols is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements for its protocols is said to be "conditionally compliant."

Using a convention which differs a lot from the generally accepted practice is still a bad idea, and must be done only if you have serious reasons to do it.

share|improve this answer
add comment

With requirements, shall / shall not. Nothing else. "Shall" is a very specific; it's a keyword I can search for. Must, must not, will, will not: That's for the explanatory text. (And no shalls in the explanatory text. That defeats making "shall" a search term.)

How not to do it: I helped write a proposal long ago where the RFP had shall requirements, should requirements, shall options, and should options. What a mess! A viable proposal had to meet all of the shall requirements and the shall options, and had to address all of the should requirements ("we can't do this" was one way to address those things). Should options were optional. The base offered price had to cover all of the requirements (shall and should); options had to be priced separately and individually. We didn't win; nobody did. Someone high up eventually put a stop to that convoluted RFP.

With tests, shall and should don't belong. The test criteria says how to interpret the results of the test: Did the test pass or did it fail? The criteria might be plain English, a boolean, math, but not shall. There's no reason to say shall. That the test must eventually pass is implied.

share|improve this answer
add comment

You certainly could use "shall" in this fashion, and it would not be a bad thing, but don't expect your programmers to know the difference. I never saw this usage during fifteen years of writing code from formal specs, so probably a lot of other coders haven't either. If you have a use for the distinction, go ahead, but be careful to explain what you're doing.

share|improve this answer
add comment

Background: I speak from the viewpoint of roughly thirty years experience, almost all of it in the defense industry (except for two years in telecom, at Nortel Networks).

Definition: A requirement is something that you are required to verify. You may verify by analysis, by demonstration, by test, by mathematical proof, or some other approved way, but you absolutely must verify that your product meets that requirement. If your product doesn't meet that requirement, or if you have not PROVEN that your product meets the requirement, you aren't done.

In the defense industry, at least, a statement in a requirements specification is considered to be a requirement if and only if it uses the word "shall". There are no exceptions whatsoever to this rule. If it said "shall", it was a requirement, if it didn't, it wasn't. Period. End of sentence, end of paragraph, end of chapter, end of book.

This makes it VERY easy to decide whether a particular statement in a requirements specification is or is not something that must be tested, or otherwise verified.

RFC2119 formalized terms of art long used for writing RFCs. At the time the original RFCs were written, long before RFC2119 was penned, the original RFC writers, who were very familiar with defense industry specification conventions, were trying very hard to avoid appearing as though they were writing requirements specifications for the net as a whole. The very name, "Request For Comments", was chosen for that specific reason, to avoid dictating to the other researchers. (Herding cats is a lot easier than herding researchers.) Hence they carefully avoided using the word "shall", and used "must" instead. The idea was the same: if you wanted to write e.g. a Telnet client, and claim it conformed to the Telnet RFCs, you were required to comply with the "must" statements.

During my short stint in telecom, I did have to read RFCs, and I did have to read and write non-RFC requirements specifications. The RFCs all used "must" to denote requirements. The requirements specifications all used "shall" for that purpose.

If I were in your shoes, and writing non-RFC requirements specifications, I'd use "shall", and only "shall", to denote requirements and only requirements, for the reasons described above. Similarly, if you're writing RFCs, use the RFC 2119 language, and incorporate RFC 2119 in your RFC as the other guy described.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.