Do requirements matter?

For the last decade, I've met in my life hun­dreds of French pro­gram­mers, de­vel­op­ers, leads and CTOs. None of them knew the dif­fer­ence be­tween func­tion­al and non-func­tion­al re­quire­ments.

This wouldn't be so dis­turb­ing if it were lim­it­ed to France: in­deed, in coun­tries like France, In­dia or Al­ge­ria, the lack of for­mal, high qual­i­ty ed­u­ca­tion in IT sec­tor, and the lag of most com­pa­nies makes it dif­fi­cult to ex­pect a bit of for­mal­ism from IT staff. The prob­lem is that it's not.

The rev­e­la­tion was this ques­tion on Pro­gram­mers.SE:

I'm won­der­ing about func­tion­al or non-func­tion­al re­quire­ments. I have found lot of dif­fer­ent de­f­i­n­i­tions for those terms and I can't as­sign some of my re­quire­ment to prop­er cat­e­go­ry.

I'm won­der­ing about re­quire­ments that aren't con­nect­ed with some ac­tion or have some ad­di­tion­al con­di­tions, for ex­am­ple:

1. On the list of se­lect­ed de­vices, de­vice can be re­peat­ed.
2. Data­base must con­tain at least 100 items
3. Cur­ren­cy of some val­ue must be in USD dol­lar.
4. De­vice must have a name and pow­er con­sump­tion val­ue in Watts.

are those re­quire­ments func­tion­al or non-func­tion­al ?

The ques­tion re­ceived 10 an­swers (some were delet­ed and can be seen only by users with enough rep­u­ta­tion):

• 2 an­swers (mine and the ac­cept­ed one) are the right ones.
• 1 an­swer is a (rel­e­vant and some­how use­ful) com­ment.
• 7 an­swers show a com­plete mis­un­der­stand­ing of the sub­ject. Among those an­swers, some are post­ed by a high­ly re­spect­ed mem­bers of Pro­gram­mers.SE who are very skill­ful and ex­pe­ri­enced de­vel­op­ers.

Now that's a real prob­lem. Not be­cause those peo­ple were an­swer­ing ques­tions on a sub­ject they know noth­ing about—Stack Ex­change is a Q&A web­site, not an en­cy­clo­pe­dia—but be­cause they, with their broad ex­pe­ri­ence in soft­ware de­vel­op­ment, are un­aware of the an­swer in the first place.

Why would it mat­ter?

The lack of prop­er re­quire­ments is one of the caus­es why IT pro­jects fail. Oth­er caus­es in­clude but are not lim­it­ed to hir­ing un­skilled per­son­nel, not man­ag­ing soft­ware pro­jects, not en­sur­ing de­cent work­ing con­di­tions and per­ma­nent­ly ly­ing to cowork­ers and cus­tomers.

I've done dozens of pro­jects, and I've nev­er seen one with at least a read­able spec.

Nev­er.

Gen­er­al­ly, things hap­pen this way in a cor­po­rate en­vi­ron­ment:

1. A cus­tomer meets a rep­re­sen­ta­tive (of­ten a sales­man) of the com­pa­ny to dis­cuss the pro­ject. Great, two per­sons who know noth­ing about soft­ware de­vel­op­ment are dis­cussing the ma­jor as­pects of the fu­ture prod­uct.

2. A rep­re­sen­ta­tive of the cus­tomer meets the pro­ject man­ag­er—of­ten a for­mer pro­gram­mer with no for­mal ed­u­ca­tion in ar­chi­tec­ture, de­sign or re­quire­ments gath­er­ing—to draft the de­tails. Parkin­son's Law of Triv­i­al­i­ty en­sures that the draft con­tains use­less and an­noy­ing el­e­ments such as the col­or of the hy­per­links, but lacks the most im­por­tant as­pects of the prod­uct.

3. The draft be­comes de fac­to “The Spec”.

4. Pro­gram­mers at­tempt to read this draft (most coura­geous ones even try to un­der­stand it) and ask ques­tions.

5. The man­ag­er an­swers the ques­tions, based on his own un­der­stand­ing (or the lack of un­der­stand­ing) of the pro­ject.

6. The cus­tomer re­quests hun­dreds of changes which nev­er find their way in the spec. If the spec is changed, ei­ther it be­comes ob­so­lete few days lat­er (and not changed then) or, more of­ten, it is al­ready ob­so­lete once the changes are writ­ten.

Such “spec”—if we are al­lowed to use this term—is not just use­less; it is par­tic­u­lar­ly harm­ful. It blocks cre­ativ­i­ty. It wastes mon­ey. It makes it pos­si­ble for the com­pa­ny to have an ex­cuse for be­ing late: “We couldn't de­liv­er on time, be­cause we are ac­tu­al­ly work­ing on ad­di­tion­al fea­tures which are not in the spec”.

Every spec I've seen is a com­plete waste of re­sources, with no ben­e­fits what­so­ev­er.

Once we un­der­stand that, we have a choice. We can cre­ate a real spec­i­fi­ca­tion, or we can skip this step and do some­thing else. The choice is easy to make:

• If the pro­ject is Ag­ile, the spec is not par­tic­u­lar­ly use­ful—there are valid cas­es were I ac­tu­al­ly wrote a com­plete spec­i­fi­ca­tion for an Ag­ile pro­ject and it would have been a mis­take of not do­ing it, but it's bet­ter to work with­out a spec than to have an er­satz of a spec con­stant­ly harm­ing the pro­ject and the team.

• If the pro­ject is not Ag­ile (and su­pe­ri­or to one man month), you ab­solute­ly want to have a de­cent spec, and you ab­solute­ly want to do it cor­rect­ly.

Imag­ine you're build­ing a house. In Ag­ile world, you don't know yet what do you need ex­act­ly: you might need a pool in the back­yard, but you're not sure. You might need a garage for two cars, but you're not sure if your wife will ac­tu­al­ly de­cide to buy the car she want­ed. If con­struc­tion were sim­i­lar to soft­ware de­vel­op­ment, you could be tak­ing (and chang­ing) those de­ci­sions dur­ing the con­struc­tion with only mi­nor im­pact on the over­all cost of your house.

In non-Ag­ile world, you have to know every­thing in ad­vance. If your wife buys a car once the garage is built, it would be ex­treme­ly ex­pen­sive to make the garage larg­er—very prob­a­bly, you'd have to de­stroy the one which was built, and build an­oth­er one. Now imag­ine that the house is built on the fol­low­ing spec:

Well, I want a house with... I don't know... five or six rooms, but I'm re­al­ly not sure. Re­mem­ber to make the bed­room large enough. There should be a garage as well. And a pool some­where. Just don't for­get, this is very im­por­tant, I want the walls be paint­ed in light blue, and please make a few large win­dows.

Will you get the house of your dreams based on a spec like this? I don't think so, and that's also why most cus­tomers don't get the prod­ucts they want.

For­mal­ism

Once you un­der­stand that you need a real spec, the next thing to un­der­stand is that a spec should be writ­ten by a per­son who knows her job. This is not a sim­ple writ­ing task, but a task which also re­quires a lot of rig­or, pre­ci­sion, think­ing, un­der­stand­ing. To do this task cor­rect­ly, for­mal ap­proach helps a lot.

The manda­to­ry for­mal­ism also means that one should clear­ly un­der­stand some as­pects of:

• Re­quire­ments elu­ci­da­tion—the task of (1) ex­tract­ing the rel­e­vant re­quire­ments from the in­put giv­en by the cus­tomer and the end users and (2) fil­ter­ing the el­e­ments which are ir­rel­e­vant to the pro­ject or should be made by ex­perts: UX de­sign­ers, se­cu­ri­ty ex­perts, an­a­lysts, etc.,

• Re­quire­ments writ­ing—the task of writ­ing down the re­quire­ments in a for­mat which makes them us­able by the de­vel­op­ers. The re­quire­ments need to be sort­ed, grouped, and for­mu­lat­ed in a non-am­bigu­ous way which makes no room for in­ter­pre­ta­tion.

This sec­ond task is as, if not more im­por­tant as re­quire­ments elu­ci­da­tion, and this task re­quires a clear un­der­stand­ing of the dif­fer­ence be­tween func­tion­al and non-func­tion­al re­quire­ments. At this lev­el, it is es­sen­tial to un­der­stand that all re­quire­ments are ob­jec­tive, that all should be ex­pressed in a way which makes it pos­si­ble to write a test which ei­ther pass­es or fails.

Screw­ing at this lev­el is a good way to fail the pro­ject.

This is why I'm so dis­ap­point­ed when I see on Pro­gram­mers.SE an­swers such as:

They're func­tion­al, be­cause you could write a sim­ple func­tion or read the doc­u­men­ta­tion to test whether or not this was the case.

Non-func­tion­al re­quire­ments are in­her­ent­ly sub­jec­tive, like, "Must be fast, must be user-friend­ly, etc."

Every re­quire­ment should be writ­ten in a way that it can be trans­lat­ed into a test. Some­thing which is in­her­ent­ly sub­jec­tive has noth­ing to do among the re­quire­ments.

The best way to check if the re­quire­ment is writ­ten cor­rect­ly is to ask your­self:

• Can I write a test which checks for this re­quire­ment?

  If the an­swer is “No”, this is not a re­quire­ment.

• Can I write a fail-pass test which checks for this re­quire­ment?

  Some re­quire­ments are re­luc­tant to fail-pass (red-green) TDD style tests. If too many re­quire­ments are in this case, this is a bad sign, but don't wor­ry if some are.

  Note that this is very dif­fer­ent from unit tests. In unit tests, fail-pass should be pos­si­ble for every test. In a case of func­tion­al and non-func­tion­al re­quire­ments, sys­tem tests of func­tion­al tests may be ex­treme­ly com­pli­cat­ed, which means that you will be able to im­ple­ment a test which only pass­es, but can't make it fail de­lib­er­ate­ly eas­i­ly enough.

• May oth­er per­sons in­ter­pret this re­quire­ment dif­fer­ent­ly?

  If yes, it is bad­ly writ­ten. A cor­rect­ly writ­ten re­quire­ment is not sub­ject for in­ter­pre­ta­tion.