The software development industry is still in its early days. Compared to other industries with centures of history and evolution behind them, software development is only beginning to mature. One of the consequences of that relative immaturity is that we still have many recurring problems to solve. In this article, I'm going to talk about one of the most important ones: communication. 

Screen shot 2010-12-10 at 10.15.09 .pngCommunication is key to developing the right software the right way. No matter how good a development team is, if they cannot understand the problem the software needs to solve, they will not be able to deliver what their clients really need. One of the best approaches to mitigate communication problems is a set of techniques known as Specification by Example.

The term, introduced by Gojko Adzic, refers to techniques that have in common the specification of software requirements using examples, as the name suggests. The most well known of these techniques is BDD, or Behavior Driven Development.

Essentially, these techniques tell us to describe the software using stories, with real case examples whenever possible, and to share those stories with the whole team. The recommendation is to involve the team in the writing, in fact, and use the stories to ascertain that the software really does what is specified. There is even a language created to make it easier (Gherkin) and tools like Cucumber and Specflow that make executable tests out of these specifications.

Most developers nowadays are familiar with the term BDD, or at least TDD (Test Driven Development). Many quality assurance analysts use it to write their tests. Business analysts also use the Gherkin language to describe the requirements. But the true power of Specification by Example comes when everyone works together, a technique known as The Three Amigos.

I will not go into details about how it works here - my intention is to show the benefits, leave some references, and let you try it out. I can assure you it will be worth it!


Why bother?

Bridging the Communication Gap

Specification by Example brings a lot of advantages with it. The first one is bridging the communication gap. The Gherkin language is made to be easy to read and can easily be understood by anyone in the team, even business people, without any knowledge of computer programming. Furthermore, the same specification can be used throughout the whole process by business analysts, software developers, and quality assurance analysts. Even the client can have access to the specification by using a tool like Pickles.

image05.pngUsing this common specification, developers can implement what the business analysts agreed is necessary, and quality assurance analysts can verify that the implementation is correct. A unique source of specification helps to avoid situations where a developer uses a different definition than the other members of the team.

Giving Directions

image06.pngSoftware must do what its specification says, and each part of its implementation must be validated to ensure that it does. These validations must be repeated every time anything changes in the software, to ensure the software still does what it is expected to do. Additionally, the software must also be documented so that new team members can understand what it does.

Test-driven development is a good way to test and self-document the software, but defining what to test is not always easy. In most cases, the developer will not know what is necessary to test, which in turn means the developer is left unsure as to what ought to be implemented.

The existence of a human readable specification, created by developers, business analysts and quality assurance analysts together, solves this problem by making it clear to the developer what must be implemented and what must be tested.

Another advantage of these techniques is that the specification is split into scenarios. Each scenario has a unique set of preconditions, a small set of actions, and expected postconditions. This way, it is easy to pinpoint what conditions are causing a test fail.

Valuing the Code Quality

image02.pngTests that verify the behavior of the software, feature by feature, scenario by scenario, allow the developer to be confident in her work. She will not only know that she met the requirements for a new scenario but also know if her changes broke anything else. With this confidence, it is easier to do design refactorings, pay technical debts, and apply the Boy Scout rule. This confidence makes the code better every day. Altogether, it will motivate developers to keep tests updated and make it a habit to always have a specification before the begin to code.

Strengthening team bonds

image04.pngUsing Specification by Example, everyone can learn about the business during the specification and development processes. Disputes about who is right are reduced, since the specification is the same for everyone and was created collaboratively. Some teams even dedicate a pre-iteration time just to get everyone together to write the stories and clarify them for everyone. During these moments, business analysts can bring a business point of view, developers can recognize technical issues, and quality assurance analysts can identify edge cases. Each team member brings their own strengths to the process.

A specification created collaboratively makes everyone feel like part of the team, with shared responsibility for the end product. Now it’s not that guy s responsibility anymore, it’s ours. And we are going to make sure it’s correct and addresses the client needs.


Specification by Example is more than writing specification using examples. It demands the integration of the team, it results in executable tests, and ensures quality work. Without Specification by Example, these aspects are often overlooked, or never even considered.

What do you think about Specification by Example? How much of it have you tried? Leave your opinion in the comments. For those wanting to learn more about the subject, try reading the book Specification By Example, which chronicles the extensive research Gojko Adzic  about this subject.


Rafael Romão

.NET Engineer at Avenue Code. I study software development since 1998 and work as software developer since 2002. My main areas of interest are software architecture and design, as well as the development of highly productive teams.