Fabio Pereira

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 extends DSL> T given(T dsl) {
    return dsl;
  }

  protected <T extends DSL> T when(T dsl) {
    return dsl;
  }

  protected <T extends DSL> T then(T dsl) {
    return dsl;
  }

  protected <T extends DSL> 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.

Technical BDD, Code, Java, TDD

One of the advantages of being a consultant is getting to see different environments and being able to visualise and identify patterns and anti-patterns.

“An anti-pattern is a pattern that may be commonly used but is ineffective and/or counterproductive in practice” http://en.wikipedia.org/wiki/Anti-pattern

As a first step, let’s describe TTDD – Tautological Test Driven Development as an anti-pattern of TDD (TestDrivenDevelopment). In fact TTDD is a big enemy of the combination BDD (BehaviourDrivenDesign) and TDD.

I still have the vivid memory of the day that I was pairing with Dave Coombes and he mentioned that one of the tests I had written was tautological.

Tautological:
- needless, redundant repetition of an idea
- repetition of same sense in different words;
- the phrase “a beginner who has just started” is tautological

I did not quite understand at first why the test was tautological, i.e. needless, redundant.
As a perfect leader and coach that Dave is, he helped me rewrite the test in a different way and that was when I finally understood what he had meant by that.

Example

The example below is simplified version of the one that Dave and I were using at the time.
In this example, we want to test the class CarRepository that interacts with 2 collaborators as shown below:

In order for CarRepository to retrieve all the cars from CarService it needs a ServiceHeader that is provided by ServiceHeaderFactory. For the purposes of this example, I’ll show the implementation of CarRepository:

public class CarRepository {
  private ServiceHeaderFactory serviceHeaderFactory;
  private CarService carService;

  public CarRepository(ServiceHeaderFactory serviceHeaderFactory,
                    CarService carService) {
    this.serviceHeaderFactory = serviceHeaderFactory;
    this.carService = carService;
  }
  public Cars findAll() {
    ServiceHeader serviceHeader = serviceHeaderFactory.create();
    return carService.findAll(serviceHeader);
  }
}

Tautological Test

The test below is similar to the one I wrote that we described as tautological:

@Test
public void shouldRetrieveCarsFromCarServiceUsingTheRightServiceHeader() throws Exception {
  // GIVEN
  ServiceHeader serviceHeader = new ServiceHeader();
  ServiceHeaderFactory serviceHeaderFactoryMock = mock(ServiceHeaderFactory.class);
  when(serviceHeaderFactoryMock.create()).thenReturn(serviceHeader);
  CarService carServiceMock = mock(CarService.class);
  CarRepository carRepository = new CarRepository(serviceHeaderFactoryMock, carServiceMock);

  // WHEN
  carRepository.findAll();

  // THEN
  verify(carServiceMock).findAll(serviceHeader);
}

Why is this test called Tautological?

One of the definitions of a tautology is: “repetition of same sense in different words”

If you look carefully at these 2 lines of implementation and 2 lines of test:

Test

• when(serviceHeaderFactoryMock.create()).thenReturn(serviceHeader);
• verify(carServiceMock).findAll(serviceHeader);

Implementation

• ServiceHeader serviceHeader = serviceHeaderFactory.create();
• return carService.findAll(serviceHeader);

They are almost “equivalent”. When we write tests this way, most of the time if the implementation changes, we end up changing the expectations of the test as well and yeah, the tests pass automagically. But without knowing much about its behaviour. These tests are a mirror of the implementation, therefore tautological.

The test below verifies the same class CarRepository, but as a black box test, i.e. it does not test the interactions, but the output of the repository. Look at the assertion.

@Test
public void shouldBeAbleToRetrieveCars() throws Exception {
  // GIVEN
  Cars carsFromService = new Cars(new Car("Ferrari"), new Car("Porsche"));
  CarRepository carRepository = givenARepositoryAttachedToACarServiceWithCars(carsFromService);

  // WHEN
  Cars carsFromRepository = carRepository.findAll();

  // THEN
  Assert.assertEquals(carsFromService, carsFromRepository);
}

private CarRepository givenARepositoryAttachedToACarServiceWithCars(Cars carsFromService) {
  ServiceHeader serviceHeader = new ServiceHeader();
  ServiceHeaderFactory serviceHeaderFactoryMock = mock(ServiceHeaderFactory.class);
  when(serviceHeaderFactoryMock.create()).thenReturn(serviceHeader);
  CarService carServiceMock = mock(CarService.class);
  when(carServiceMock.findAll(serviceHeader)).thenReturn(carsFromService);
  CarRepository carRepository = new CarRepository(serviceHeaderFactoryMock, carServiceMock);
  return carRepository;
}

There is still a big effort to setup the mocks and inject them into the repository. This has been extracted to the method givenARepositoryAttachedToACarServiceWithCars. However, all these mock setups make it harder to understand the intent of the test, the responsibility of the class that we are trying to test. When this happens I usually tend to use stubs instead of mocks. Here is the same version of the tests, but using Stubs:

@Test
public void shouldBeAbleToRetrieveCars() throws Exception {
  // GIVEN
  Cars carsFromService = new Cars(new Car("Ferrari"), new Car("Porsche"));
  CarRepository carRepository = givenARepositoryAttachedToACarServiceWithCars(carsFromService);

  // WHEN
  Cars carsFromRepository = carRepository.findAll();

  // THEN
  Assert.assertEquals(carsFromService, carsFromRepository);
}

private CarRepository givenARepositoryAttachedToACarServiceWithCars(Cars carsFromService) {
  ServiceHeaderFactory serviceHeaderFactory = new ServiceHeaderFactoryStub();
  CarService carService = new CarServiceStub(carsFromService);
  CarRepository carRepository = new CarRepository(serviceHeaderFactory, carService);
  return carRepository;
}

It is not a rule, but I find that tautological tests have more mock setup. When we start to think about the collaborators as stubs, the tests become more behavioural.

What are the common characteristics of a Tautological Test?

• Asserts more interactions with collaborators than the outputs;
• It doesn’t really test the behaviour of the class, but only its implementation
• The test is too white box
• Too much mock setup deviates the intent of the test
• Adding a new feature or changing an existing one requires changing mock expectations

Technical Code, Java, TDD

DRY is a concept applied quite broadly in code. In a web application it’s also important to extrapolate its use to the view layer (MVC) in order to increase clarity and consistency.

At the end of this post I’ll explain how a user story that had to be delivered became much easier to implement because we had a dry and refactored view.

Concrete example of a view pattern being refactored and dryed

As I usually try to explain things by example, I’ll show a JSP that can be refactored and dried. Please notice that the idea of refactoring and drying your view using conventions is technology agnostic and can be achieved with other languages and frameworks as well.

Let’s say we have to implement this form:

The example below shows one way of implementing the aforementioned form using Spring MVC JSP tags.

The convention used was that the default label will be label.${id}.

Tag Files and Conventions
If you want to know how to create your own JSP 2.0 tag file, like the one created above (form-ext:inputText), here are a few tutorials.
But always remember about the conventions over configurations.

Here is the file that was used to implement form-ext:inputText:

You can download it if you want: inputText.tag

If the user of the tag (inputText.tag) still wants to send the parameters label, size and maxlength, they would be able to do so. They are not required and have default values, though.

Basically if you apply these two concepts (Tag Files and Conventions) you can dry your JSP’s… But you have to identify the duplication patterns.

Extract Tag File - A view refactor similar to Extract Method

What was shown above is a step by step of a refactor that I call Extract Tag File. It’s quite similar to extracting a method, but instead of code, we have JSP.
I wish the IDEs had this refactor implemented … Who knows someday… Or maybe we could write a plug-in for Eclipse or IntelliJ.

How we applied this on a real project to deliver business value quickly

Recently, on my current project, we had to change the way the error messages were shown to the user. They had to be field context aware, which means that if there was an error related to the field “Given Name”, the error message had to be show next to the field.

This is what we had before:

This is what we had to implement:

Can you imagine how much easier it was just because we had our DRY VIEW? Our fields were wrapped and, therefore, it was just a matter of implementing this inside the tag file…

That’s what we aim… Deliver business value quickly!!! Happy client… Happy developers…

Technical Agile, Code, Java

Do you think it would it be easier to maintain, understand and increment a code where all the variables that represent the same “thing” are named consistently throughout the code base?

Pat talks about “differences that cause your project death”, I wanted to explore a little bit more one of them: Naming…

Have you ever seen something similar?

PersonalBankAccount account
...
PersonalBankAccount personalAccount
...
PersonalBankAccount bankAccount
...
PersonalBankAccount pAccount
...
PersonalBankAccount pba
...
PersonalBankAccount pbAccount

Different names would help if they add any value to the instance, but the aforementioned examples are a result of different “coding styles” amongst different developers. Some of us like to type, others like to use code completion and it’s dependent on the IDE they are using.

Most of the projects that I’ve worked used checkstyle to enforce code standards. One of the standard checks I’ve always seen is the Naming Convention, which checks identifiers for particular code elements.
If we are following Sun coding conventions, the code below, for example, would generate a checkstyle error

public static final Year minimumYear = new Year(1900); // WRONG
public static final Year MINIMUM_YEAR = new Year(1900); // RIGHT

because a constant should follow the regular expression ^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$

So, code standards are advantageous! Therefore, we can use the same concept to avoid the PersonalBankAccount example.

What I usually do is totally informal, but I try to define with the team an initial convention, Camel Case with all the words for example,

PersonalBankAccount personalBankAccount // wherever possible

Sometimes we need more than one instance in the same block, I like suffixes:

PersonalBankAccount personalBankAccountToTransferMoneyTo
PersonalBankAccount personalBankAccountSourceOfMoney

This is an exception though, wherever possible, use the convention.

But always bear in mind that this is not a rule that you can’t break, it’s just a convention…

I have never seen any tool, or checkstyle check, that could generate something like:

“Number of different instance names for class T”, maybe it’d be interesting… But that’s another, another, another level…

Technical Code, Java