Wherefore Thou Shalt Fail at Software Requirements

On Being Deliberately Unclear

For whatever reason lately, I’ve been drawing a lot of inspiration from Programmers’ Stack Exchange, and today brings another such post. However, unlike other questions, reading this one seriously made me sad. The questions, the answers, its existence… all of it made me sad in the same kind of way that it’s vaguely depressing to think of how many hours of our lives we lose to traffic jams.

I had a conversation with a coworker once that involved a good-natured disagreement over the role of legalese in our lives. My (cynical) contention was that legalese has evolved in purpose–has even self-bastardized over the years–to go from something designed to clarify communication to something that is specifically used to hinder communication. To put it another way, by freezing the language of law in pedantic and flowery period-speak from the 18th century, lawyers have effectively created a throwback to the feudal practice of having a language for the nobles and a different language for the commoners. This language of the lawmaking nobles builds a bit of social job security in a way that writers of inscrutable code have picked up on–if you make it so no one understands your work and yet everyone depends on your work, then they have no choice but to keep you around. (Lawyers also have the benefit of being able to make laws to force you to need lawyers, which never hurts.)

My colleague appropriately pointed out that the nature of jurisprudence is such that it makes sense for lawyers to phrase things in documents in such a way that they can point to decided case law as precedent for what they’re doing. In other words, it’s ironically pragmatic to use language that no one understands because the alternative is that you write it in language less than 200 years old but then have to systematically re-defend every paragraph in various lawsuits later. I conceded this as a fair point, but thought it pointed to a more systemic flaw. It seems to me that any framework for bargaining between two parties that inherently makes communication harder is, ipso facto, something of a failure. He disagreed, being of the opinion that this old language is actually more precise and clear than today’s language. At this point, we agreed to disagree. I’ve since pondered the subject of language rules, language evolution, and precision. (As an aside, this bit of back-story is how the conversation went to the best of my recollection, so the details may be a little rough around the edges. It is not my intention to misrepresent anyone’s positions.)

Requirement Shock and Awe

Because of this pondering, my strange brain immediately linked the SE post with this conversation from some months back. I worked for a company once where the project manager thunderously plopped down some kind of 200-page Word document, in outline form, that contained probably 17,000 eerily and boringly similar statements:

  • 1.17.94.6b The system shall display an icon of color pink at such time as the button of color red button is clicked with the pointing device commonly known as a “mouse.”
  • 1.17.94.6c The system shall display an icon of color pink at such time as the button of color red is clicked with the pointing device commonly known as a “mouse,” 1st planet from Sol, Mercury, spins in retrograde, and the utilizer utilizes the menu option numbering 12.
  • 1.17.94.6d The system shall display an icon of color mauve at such time as the button of color purple is clicked with the pointing device commonly known as a “mouse.”
  • 1.17.94.6e The system shall require utilizers to change their underwear every half hour.
  • 1.17.94.6f The system shall require utilizers to wear underwear on the outside of their pants so that it can check.
  • 1.17.94.6g The system shall guarantee that all children under the age of 16 are now… 16.
  • 1.17.94.6h The system shalt not make graven images.

YeRequirements2A week later, when I asked a clarifying question about some point in a meeting, he furrowed his brow in disappointment and asked if I had read the functional-requirement-elaboration-dohickey-spec-200-pager, to which I replied that I had done my best, but, much like the dictionary, I had failed at complete memorization. I stated furthermore that expecting anyone to gain a good working understanding of the prospective software from this thing was silly since people don’t picture hypothetical software at that level of granularity. And besides, the document will be woefully wrong by the time the actual software is written anyway.

While I was at it with the unpopular opinions, I later told the project manager (who wasn’t the one that wrote this behemoth–just the messenger) that the purpose of this document seemed not to be clarity at all, but a mimicking of legalese. I gathered that the author was interested primarily in creating some kind of “heads I win, tails you lose” situation. This juggernaut of an artifact assured that everyone just kind of winged it with software development, but that when the barrel crashed at the bottom of the Waterfall, the document author could accuse the devs of not fulfilling their end of the bargain. Really, the document was so mind-numbing and confusing as to make understanding it a relative matter of opinion anyway. Having gotten that out in the open, I proceeded to write software for the release that was ahead of schedule and accepted, and I never looked at the intimidating requirements encyclopedia again. I doubt anyone ever did or will if they’re not looking for evidentiary support in some kind of blame game.

Well, time went by, and I filed that bit of silliness under “lol @ waterfall.” But there had been a coworker who was party to this conversation that mentioned something about the RFCs, or at least the notion of common definition, when I had been on my soapbox. That is, “shall” was used because it meant something specific, say, as compared to “will” or “might” or “should.” And because those specific meanings, apparently defined for eternity in the hallowed and dusty annals of the RFC, will live on beyond the English language or even the human race, it is those meanings we shall (should? might? must?) use. I mention these RFCs because the accepted answer to that dreadful Stack Exchange question mentioned them, clearing up once and for all and to all, including Bill Clinton, what the definition of “is” is (at least in the case of future tenses simple, perfect, continuous, and perfect continuous).

The only problem is that the RFCs weren’t the first place that someone had trotted out a bit of self-important window-dressing when it came to simple verb usage. Lawyers had beaten them to the punch:

First, lawyers regularly misuse it to mean something other than “has a duty to.” It has become so corrupted by misuse that it has no firm meaning. Second—and related to the first—it breeds litigation. There are 76 pages in “Words and Phrases” (a legal reference) that summarize hundreds of cases interpreting “shall.” Third, nobody uses “shall” in common speech. It’s one more example of unnecessary lawyer talk. Nobody says, “You shall finish the project in a week.” For all these reasons, “must” is a better choice, and the change has already started to take place. The new Federal Rules of Appellate Procedure, for instance, use “must,” not “shall.”

“Shall” isn’t plain English… But legal drafters use “shall” incessantly. They learn it by osmosis in law school, and the lesson is fortified in law practice.

Ask a drafter what “shall” means, and you’ll hear that it’s a mandatory word—opposed to the permissive “may”. Although this isn’t a lie, it’s a gross inaccuracy… Often, it’s true, “shall” is mandatory… Yet the word frequently bears other meanings—sometimes even masquerading as a synonym of “may”… In just about every jurisdiction, courts have held that “shall” can mean not just “must” and “may”, but also “will” and “is”. Increasingly, official drafting bodies are recognizing the problem… Many… drafters have adopted the “shall-less” style… You should do the same.

Bringing things back full circle, we have lawyers misusing a variant of “to be”–one of the most basic imaginable concepts in the English language–in order to sound more official and to confuse and intimidate readers. We have the world’s middle manager, pointy-haired types wanting to get in on that self-important action and adopting this language to stack the deck in CYA poker. And, mercifully, we have a group defining the new Federal Rules of Appellate Procedure who seems to value clarity over bombastic shows of rhetorical force designed to overpower objections and confuse skeptics. On the whole, we have a whole lot of people using language to impress, confuse, and intimidate, and a stalwart few trying to be precise.

A Failure of Both Clarity and Modernity

But believe it or not, the point of this post isn’t specifically to rag on people for substituting the odd “utilize” for “use,” sports-announcer-style, to try to sound smart. From academia to corporate meetings to dating sites (and courtrooms and requirements documents), that sort of thing is far too widespread for me to take it as a personal crusade. It might make me a hypocrite anyway to try. My point here is a more subtle one than that, and a more subtle one than pointing out the inherent, RFC futility of trying to get the world to agree to some made up definitions of various tense forms of “to be.”

The meat of the issue is that using slightly different variants of common words to emphasize things is a very dated way of defining requirements. Think of this kind of nonsense: “well… shall means that it’s the developer’s responsibility, but shalt means that it’s an act of God, and will means that project management has to help, and optional means optional and blah, blah blah…” What’s really going on here? I’d say what’s happening is some half-baked attempt to define concepts like “priority” and “responsible party” and “dependency.” You know, the kind of things that would do well, in, say, a database as fields. Pointy-haireds come for the semantic quibbling and they stay for the trumped-up buzz speak, so it winds up being harder than it should be to move away from a system where you get to bust out the fine verbal china and say impressive sounding things like “shall.”

The real problem here is that this silliness is a holdover from days when requirements were captured on Word Documents (or typewriters) as long, flowery prose and evaluated as a gestalt. But with modern ALM systems, work items, traceability tools, etc., this is colossal helping of fail. Imagine a requirement phrased as “when a user clicks the submit button, a JSON message is sent to the server.” That string can sit in a database along with a boolean that’s set to true when this accurately describes the world and false when it doesn’t. You want priority? How about an integer instead of bickering over whether it should be “JSON message {shall, will, ought to, might, mayhap, by-Jove-it-had-better, shalt, may, etc.} sent to the server”? When you’re coding, it’s an anti-pattern to parse giant chunks of text in a database field, so why isn’t it considered one to do it during requirements definition?

We have far better tools for capturing and managing requirements than word processors, pointless arguments over misappropriated grammar, standards used to define ARPANET in the 60’s, and polyester bell-bottoms. It’s 2013, so let’s not define and track requirements like it’s 1999… or 1969. Ditch the RFCs, the waterfall, the BS Bingo talk, and the whole nine yards if you want to get things done. But if you’d prefer just to focus on figuring out who to blame when you fail, then you should/shall/will/must/might/shalt not change a thing.