Improving the language of Feature Files

This is the first in a series of posts which are concerned with software development, specifically with the writing of Feature Files. I started this blog because I imagined that I had something interesting to say on a number of subjects. On most of these, my musings are of limited appeal, and will doubtless be lost amongst the vast quantity of more well-informed or more eloquently expressed opinion. On this particular subject though, I discover that there is relatively little published material, so I feel that I might be doing a service to others in writing about what I know, as well as satisfying my desire to commit pen to paper on whatever comes to mind.

My particular concern is the use of Feature Files as long-lived documentation that is valuable to multiple stakeholders. Here’s a diagram of the commonly regarded “Holy Trinity” of functions of a Feature File.

holy trinity.png

This post is mostly about the background to my particular interest in the largest of the above circles. For the last twenty or so years, I’ve worked in Financial Services, in Investment Banking. Like many in my field, the years since 2008 have been concerned with satisfying the increasing amount of regulatory oversight of our activities. My first involvement in this area was in writing a system to satisfy the regulatory requirements to protect client assets held by the bank in the event of its demise.

Regulators are not only concerned that firms like mine do the right thing, but also about how they do it. Part of this concern behoves us not only to to demonstrate that we understand how our systems behave, but also to provide an audit trail of documentation proving that understanding.

The system in question was one of the first that we developed using a newly adopted agile development methodology, a key part of which was the definition of the system behaviour in terms of Feature Files.

We knew in advance that the regulators and auditors would descend upon us as soon as the system was operational, and we also knew that their first demands would be to provide the standard documentation around around a project of this type – a BRD, functional and technical specifications, all of the usual rotten artefacts of an old-school SDLC. We would only have our Feature Files to fall back on, so we had to make them good!

This is where my interest in the use of Feature Files as living and lasting documents stems from. My concern is primarily about making feature files as readable and understandable as a finely crafted Word document, so that months or years after their initial implementation they still stand up as accessible descriptions of system behaviour.

Enough already with the preamble. So that this first post is more than just an essay, let’s try an exercise. Here’s an example from the Cucumber documentation describing the scenario outline gherkin syntax:

All well and good. Presumably, if you have read this far, you already know something about Feature Files, and so can understand what’s going on here. But just for the sake of argument, try putting another hat on – say the hat of a relatively technically illiterate reader. Ask yourselves these questions:

What does the scenario outline header tell you?
How do the “Given, When, Then” steps actually read in english?

Fair enough – this is a feature, illustrating a basic subtraction algorithm, that would probably never be necessary in the real world. However, suspending your disbelief for a moment, how would you rewrite this scenario to make it more easily understandable to the casual reader?

There are no right or wrong solutions to this exercise. My point is that the writing of scenarios in a feature file to make them useful as long-lived documentation is an art rather than a science. To illustrate that point, I provide two possible solutions which have been provided when I have workshopped this subject.

The first takes the example as given, adjusts the example column headers to express the problem (simple subtraction) in a domain language that suits it, and makes some simple changes to the step wording to accommodate those changes. It also adds a more meaningful scenario header:

The second example takes an entirely different approach. Understanding that the use of more than one example is redundant in this case, it proposes a different scenario style entirely, using what I call the “narrative paragraph” style:

Scenario styles will be the subject of the next post in this series. For the moment, I hope that this exercise will encourage you to start thinking more about the language of your Feature Files.

My Mother-in-Law’s Everyday Red Lentil and Tomato Dal

I have been a home cook since my teens, and had a thorough introduction to Indian cuisine through my father. He was a branch bank manager in Cambridge, and had been selected – by chance I imagine – by the prospective owners of the first Indian restaurant in the city. He was happy to help them start the business, and thereafter every new Indian restaurant that opened brought their business to him. He brought his business to them too, and we regularly visited each of them and enjoyed their hospitality and papadums!

My first, and late, wife’s family were originally from Hyderabad, India but moved to London in the early sixties, where my wife was brought up. The family were sceptical about the Englishman that their daughter brought home to meet them, but my mother-in-law was a marvellous cook, and I knew the best way to ingratiate myself would be to take an interest in the kitchen goings-on.

Over the following years, I learnt quite a few recipes from my mother-in-law, but this was the first, and is certainly the most delicious. It’s a basic dal made with red lentils, tomatoes and most importantly, curry leaves. Don’t even attempt to cook this dish unless you have these, preferably fresh ones. I’ve cooked this regularly as my children have grown up, and it’s one of our comfort foods. It can be eaten over rice, or mopped up with a chapati or paratha. It can be the main event, or a side dish. This recipe makes enough to feed three or four people as a main, or more as a side…

Ingredients:

For the dal:

1 cup red lentils, thoroughly rinsed.

3 cups water

1/2 a clove (or a small whole clove) of garlic, sliced

3-4 curry leaves

1/4 teaspoon turmeric powder

some chopped tomatoes (1 or 2 medium sized ones, half a dozen cherry or baby, or half a can of drained chopped plum tomatoes)

For the tadka:

3 tablespoons of vegetable oil

1 tsp cumin seeds

1 teaspoon black mustard seeds

3 or 4 dried small chills (or some chilli flakes will do)

6 -7 curry leaves

Method

put the lentils and the water in a saucepan, along with half a garlic clove, sliced, 3 or 4 curry leaves, the turmeric and the tomatoes. Bring it to the boil over a moderate heat,

and when it comes to the boil, skim off the foam that may form and reduce to a simmer.

Simmer for around 15 to 20 minutes until the lentils have cooked and broken up. The resulting Dal should be soupy, with the lentils settled at the bottom and a layer of liquid at the top. Add some more water if this isn’t the case.Now give it a quick stick blend. 5 seconds or so should do. You want to break up the remaining shape of the lentils, but there should still be some texture to the dal.

Now make the tadka. This is some oil with spices fried in it, which we’re going to add to the dal to give it the finished flavour. Here’s the ingredients I’ve assembled, and the dish I cook it in. It’s a small karahi, about 6 inches across, but any small frying pan or saucepan will do.

Heat up the oil, and then drop in the mustard and cumin seeds. They should fizz away if and when the oil’s hot enough. Once they’re fizzing, add the garlic, curry leaves and garlic slices. fry for a minute or maybe less, until the garlic slices are just browning at the edges.

When its like this, take it off the heat, and then CAREFULLY pour the oil and spices into the dal, which should also be off the heat. It will spit and fizz when you do, so keep your face away when you do this.

After, put the dal back on a gentle heat and stir in the tadka. Heat through and taste, now adding salt to your liking. about 1/4 teaspoon of table salt would do it for me, but try it and adjust it to how you like. As you cook it now, be careful to stir often, as the lentils will settle and may stick to the pan otherwise.

It should look like this at the end. As I said before, this dal can be poured over rice, or mopped up with a chapati or paratha. Either way, it’s delicious!

Spygate – a lesson from Carson’s Cubs

As a boy growing up in the 1960’s and early 1970’s, it was inconceivable that I should ever support any football club other than Leeds United. My family came from Leeds, and although my Dad had moved down south just as I was coming into the world, My Mum was left behind in Crossgates, a suburb of Leeds, so that I could be born in Yorkshire. The hope was that I would someday play for Yorkshire County Cricket Club I understand, but a passion for Leeds United also ran strongly in the family. My Uncle Ray was a season ticket holder, and my cousin John had the all-white strip of the Revie era. On one of our trips back North, I was sporting a West Ham strip that my friend and hero Martin Baker had convinced me into getting. I was soon put straight on a few basic principles.

I’ve carried on supporting them ever since, although of course that was a much easier job then than in recent times. Until now that is. This season has been the best for a long time, almost entirely due to the arrival of Marcelo Bielsa at the club. Bielsa clearly lives and breathes football. When he arrived, we were told that he had already watched every minute of every match from the previous season – a feat of endurance that beggars belief given some of the performances. However, his transformation of that crop of players from mid-table strugglers to league-topping performers has been remarkable. We now understand something of how that has been achieved. As well as clearly being a remarkable coach, Bielsa also seems to be a true heir to Don Revie in the amount of preparation and research he devotes to every match and every team he faces.

Which brings me to “Spygate” – the latest in a long series of excuses for the football media and hierarchy to have a pop at Leeds United. It’s a lot of fuss over very little in my view. Much has been said about the morality of peeping through the fence at your opponents training sessions, but at the end of the day no rules or laws have been broken. Mostly, the criticism has centred around the notion of fair play. This seems to me to be a bit rich when you look at the moral standards and behaviour of the Premier League clubs and players, but it did remind me of something from the distant past.

As youngsters in the 1960’s, we didn’t have much to guide us in shaping our world view – Blue Peter never explored the great moral issues of the day! Also, the amount of reading matter we had to hand was tiny compared to today. I probably had no more than a couple of dozen “Puffin” books on my shelves – Doctor Dolittle with its casual racism, Worzel Gummidge, and so on – but these were supplemented with a sporadic supply of comics.

Which brings me to the “Lion” Annual of 1969. “Lion” was a boys comic, full of war stories, wild west adventures, thinly disguised facsimiles of Tarzan (“Jungle Jak”), and football adventures, chief amongst which was Carson’s Cubs. This cartoon strip was about a football team of (literally) boy wonders, who somehow were able to compete in the world of the adult game.

I must have read this annual, cover to cover, dozens of times. I still have it, and just opening the pages I can still remember all the stories and pictures. So when Spygate came around, I instantly recalled this story…

As you will see, the story revolves around a training session which is spied upon by an unscrupulous reporter. Once this subterfuge is discovered, Joe Carson the manager stages a mock training session involving various dirty tricks (including the goalie hiding the ball up his jumper) which are then dutifully reported on the front pages of the local rag. Needless to say, the shady spy gets his comeuppance in the end…

So, Marcelo be warned!