My previous project was distributed across cities and we had almost 30 people involved. Communication and the understanding of what needs to be done are crucial for the success of the project.

One of the big challenges was to make sure that the business and the technical people shared the same domain Ubiquitous Language. To ensure that, we started using JBehave to define the acceptance criteria of the stories. Half way through, there was a big change which required many changes in the scenarios…

Some issues that we found:

• The scenarios are text files and extremely hard to refactor.
• We had to change the text files (scenarios) and the Java files and keep them in sync
• Too much duplication
• When writing the scenarios we had no such thing as auto completion
• When running the scenarios, we could not run 1 scenario at at time, but the whole file

 

The solution was to abstract our own code with a DSL layer and use it for documentation purposes. Initially we called this JMisbehave because the initial intent was to generate a read only version of the code that we could show to non-technical people and agree on acceptance criteria, as well as keep an executable documentation of the application. Code Humaniser was another suggested name…

  

Eventually we realised that the code itself was sufficient and we ended up not using the code that generated the read only version of it. Nevertheless it’s still useful in many environments. Many times we showed the code to non-technical people and they were quite delighted to see how straight forward it was to read and to understand. Moreover, it was expressing the Language of the Business. An interesting thing is that our colleague Dan North, who wrote JBehave, came to our project one day to facilitate a retrospective and we told him the whole story. He quite liked what we had done and was quite complimentary about the fact that we had understood the concept of DDD and BDD, and the fact that it’s not about the tools. It was actually his recommendation to use the_underscore_notation instead of theCamelCaseNotation, we had some discussions about that, but that will be described on another post.

Behind the Scenes - The Scenario Code DSL Implementation

James Barritt saw another post of mine with some of our Scenarios Code DSL examples and suggested that I wrote a post explaining what was happening “behind the scenes”.  Here is a high level diagram of how we separated the layers:

 

Some code:

Scenarios Code

public class Location_Scenario extends BaseScenario {

  public void should_default_risk_address_when_insured_address_is_valid_for_risk() {

    given(the_broker. has_started_a_home_quote());

    when(the_broker. selects_a_valid_location_for_risk_address());

    then(the_policy.has_home_risk_location_and_risk_address_as_same());

  }

}

public class BaseScenario {

  protected Broker the_broker;

  protected Policy the_policy;

  (...)
  protected  T given(T dsl) {

    return dsl;

  }
  protected  T when(T dsl) {

    return dsl;

  }
  protected  T then(T dsl) {

    return dsl;

  }
  protected  T and(T dsl) {

    return dsl;

  }
}

DSL Code

public class Broker extends DSL {

  public FieldEnterer enters;

  public Policy the_policy;

  public Broker blah() {

     // call implemenation

    return this;

  }

}
public class Policy extends DSL {

  public FieldEnterer enters;

  (...)

  public Policy blah() {

     // call implemenation

    return this;

  }

}

This was a project with lots of people coming in and out all the time and every time someone new would join, the time taken to understand the code and relate it to the business terminology was extremely reduced by the way our tests were written.
You can do the same on your project, write your tests using the language of the business.