Given-When-Then is an efficient method to document testable, use-centric descriptions of expected system behavior. With functionality as its cynosure, GWT does not prescribe how to denote design, capture context, or log logic. The practices described herein were fashioned with development teams comprising decades of experience; they are offered as a tool for enhancing your requirements.

Comments for Context

Applying comments to Given-When-Then requirements necessitates that one first understand GWT’s function as pseudocode; like code, comments in pseudocode are not executable. Programmers do not turn comments into commands. Testers do not test them.

NASA’s lunar landing code offers a wonderful example of developer comments. The dark text on the left is the assembly language that would, after compilation and hand-weaving into rope memory, be executed by the computer, while each octothorp and everything after it is a comment.

NASA lunar lander assembly language
GitHub

When the language consists of such terms as “NOTHROTL” and “IGNALOOP DLOAD” the value of comments is evident.

Given-When-Then is a language designed to be more human-readable than assembly language, of course, but nonetheless occasionally improved by a bit of context. One way to denote comments is using the C# standard // as these are easy to type, unambiguous characters.

Given the input field is displayed
When the user inputs a value that IS divisible by 5 // already limited to only whole numbers
Then display: Buzz

The comment “// already limited to whole numbers” tells programmers that restricting the field's input has already been implemented. Otherwise, they would be right in asking “What happens if the user inputs 5.4?” and pausing until they got an answer.

As is, the above paragraph, even with its comment, leaves questions unanswered: what are the upper and lower limits a user can enter, how big should “Buzz” be displayed, what if the user inputs letters. Some of these may be addressed by other requirements or not worth considering given system limits, but one should be glaring obvious.

True Can Be False

Computers use Boolean logic. Because it has been abstracted away, this is easy to forget, yet for those charged to documenting software functionality it is vital to remember. Being built on Boolean means that if something in a program can be true, it can also be false. If one has written a requirement about what happens when something is, one must also account for when it is not. To complete the paragraph from the above section:

Given the input field is displayed
When the user inputs a value that is NOT divisible by 5
Then do NOT display Buzz

This completes the binary. However, a bit of room has been left for ambiguity and potential crazy-making: what if the input is not divisible by 5 and anything except “Buzz” is displayed?

Negative Requirements

No. Functional requirements state what should happen, not what should not happen. If it is not stated, it should not happen. Otherwise, writing requirements would become nigh impossible as one dreams up all the things that should not be.

Negative requirements are different from completing Boolean logic. The latter completes a binary—if true, this; if false, this—while the former is only the false half with a potentially infinite number of imaginary situations.

Given the input field is displayed
When the user inputs a value that is NOT divisible by 5
Then do NOT display Fizz
And do NOT display Pop
And do NOT display Soda

The consequences of negative requirements are immediately obvious to anyone who has seen certain pedestrian walkways or been a teenager. “No biking, you say? How about no skateboarding? No skateboarding. How about no rollerblading?” Simply say: walking only.

Positivity About Negative Requirements

Among those with a predilection for pendently in programming, there is much debate about the principle of positive requirements. Some argue negative requirements are essential. Negative requirements often surface in conversations about performance—a process is taking too long, a service must not go offline—in these cases, the need can be readily rewritten as a positive functional or quality requirement.

However, there is one circumstance in which negative functional requirements prove beneficial. Anyone who has worked with legacy software has likely experienced inexplicable behavior.  Perhaps a button opens a window for no apparent reason.

Given the input field is displayed
When the user inputs a value that is NOT divisible by 5
Then do NOT display Purple // like it does now… for some reason…

Perhaps the window once had a message that it has long since been forgotten, yet the window lingers. When modifying existing software, it is helpful to state what needs to stop happening.