Yeah, but Where's India?: Impressions of Specification by Example

Cristoforo Colombo (a.k.a Columbus) knew how to sail, navigate, sell a proposal. He was commissioned to find a new route to India. He didn’t find India. Fortunately for him and his career, he found something even more lucrative.

You’ve got skills, right? Coding skills, architectural skills, fried skills, skills gumbo, nun-chuck skills… But if you’re commissioned to write a piece of software that takes your stakeholders to India, how will they feel when they wind up somewhere in the Caribbean? You could pull a Columbus and try to convince yourself and everyone else that they really are in India:

You: “But this is India, I tell you! See? Look at those Indians. You there! Yes you, Indian! Come hither at once!” Stakeholder: Raises a doubtful eyebrow. Takes a long, exasperated breath. “Indian”: “Oye papi. ¿Sabe? Tu ta loco.”

The point is: you know how to code, but are you coding the right thing? How do you know? That’s where Specification by Example comes in.

The book’s author, Gojko Adzic, took a bunch of practices from ATDD, BDD and DDD, performed a taxonomic reboot, and out popped Specification by Example (SbE). The result is a series of process guidelines that are highly understandable, practical, and in many cases, immediately actionable from where you’re standing right now.

Communication is Key

The hardest part for many of us nerds is that the secret to building the right product involves actual communication, not with some obtuse and unforgiving networking protocol, but with other biological entities - specifically obtuse and unforgiving two meter bipeds. Adzic pulls from Behavior Driven Development (BDD) with its focus on building the right software through structured conversations within the ubiquitous language of the domain. Throughout the book he stresses the importance of actual face-to-face communication between everyone involved in making the software: Clients, stakeholders, developers, testers, etc. If they have a part, you should be talking to them.

Examples

In the world of specifications, examples are where it’s at. Examples lift your specs from the lifeless realms of abstract diagrams and obtusely wordy paragraphs and send them soaring through an endless cobalt sky… (Example: Picture a hot air balloon taking off from a bleak 2D landscape and sailing through the wide open deep blue sky of reality. ;-)

Examples are great when you’re writing specifications because they help you flush out inconsistencies and missing requirements. Long-winded specs tend to seem more complete than they really are, and they’re harder to wrap your head around. You may be tempted to just assume they’re correct and go grab a cup of coffee rather than slog through them. An example helps you to quickly form a mental model, and your experience will tell you if that model is missing something. Pretty sweet.

Adzic practices what he preaches in his writing; the book is overflowing with examples illustrating the main points, including anecdotes from real software development outfits which have put the principles of SbE into practice.

Layout

About half the book deals with gathering the key examples that illustrate your core domain and then refining them into a concise, readable, and maintainable set of specifications.

After that, the focus is on breathing life into your Specifications with Examples and transforming them into the ultimate goal - Living Documentation.

Living Documentation is where you create a suite (or suites) of acceptance tests which automatically and frequently validate your specifications. They make sure that the specs harmonize with what the software is actually doing.

Taxonomic Reboot

One of my favorite aspects of the book is how Gojko refactored many industry terms to more closely align with their actual function. Naming stuff is hard; so when our ancestors labored unsuccessfully to come up with good names for a newish software practice, they just threw “dynamic”, “extreme “, and “driven” into a hat, shook it up, and pulled out a new moniker. Of course, this naming practice has itself come to be known as “Extreme Lightly-Salted Pseudo Random Name-Driven Dynamism.” (/* Contains MSG */) I mean, with all the dynamic driving going on in our industry, I’m convinced that our worthy forerunners were all moonlighting as NYC cabbies. ;-)

Yes, I highly recommend the book. Especially if you’re plotting a new route to India. Otherwise you may wake up one century and find that they’ve changed your name from Colombo… to Columbus.