Thursday, 13 September 2012

Which came first, contract or code?

Another recurring theme that I keep seeing time and time again on my travels is the debate between communities about which should come first. Contract or code. I see a place for both in service development and decided to explore the reasons for why that is.

Code-First Development

Code first development is defined as delivering a working system, refactoring and splitting the code ito a separate subsystem along a 'natural' boundary. At this point, the teams themselves can be split into two, one for either side of the service contract.
Consider a fabricated shopping basket example. A simple shopping basket is developed as one monolithic and to end function, which sums the prices of the items in them, calculates the tax on the order and renders itself on screen.
A step in refactoring may introduce an MVC pattern and split out the tax calculation using a strategy pattern.
Once split, the taxation interface may be considered a separate domain, natural to split on. The team itself then splits too, with some members then going on to work on the taxation service whilst others remain on the web component.

fig 1 - Code first development
This is the method normally advocated by XP and SCRUM proponents.


  • Knowledge of the contract doesn't have to be agreed up front - The contract is defined by refactoring to it and emerging the design over time.
  • Team size can be small, then increase until a natural fracture point in the architecture necessitates the split of the code and the team. This maintains Conway's law.
  • Delivery is assessed by acceptance criteria associated with end-to-end business processes.
  • Very useful for delivering software where the business process is not fully known.
  • Delivers more optimum results inside departmental systems.
  • Breaking changes where split teams do not communicate effectively is higher.
  • Where end-to-end business value is outside the scope of the development team, or they do not have full control/visibility of the end result (such as interacting with COTS systems) and the success criteria doesn't account for they integration work, this can be difficult to get right and the service contracts may not match actual expectations.
  • The services do not evolve to represent the business value until later in the process - message passing between departments does not necessarily evolve from the microscopic view of the role of the technical contracts.
  • Cross-team communication is essential, so the split teams will have to sit near each other to communicate effectively. As the service catalogue grows, this becomes a much more difficult task.
  • Can miss the wider optimisations as the bigger picture is never addressed during 'emergent design'. The resulting optimisations are effectively sub-optimal at the organisation level.

Contract-First Development

By contrast, contract first development is delivered from the identification of messages flowing between the business functions, utilises techniques such as design-by-contract to define message and service contracts between the departments and their systems, which then become the acceptance criteria for the code developed by different teams independently on either side. Automated validation is performed on both sides against the contract using service stubs and a standard interface definition (such as an XSD).

An example process might be:

fig 2- Contract first definition
  • Architecture and management, who know the bigger picture of the organisation (if one exists) can help define the detail of the business process and hence, contract obligations.
  • Both teams can work independently at an earlier stage and get to a standard contract definition much quicker.
  • Very useful in static, well defined companies with well defined departments and divisions.
  • Much easier to apply Conway's law.
  • Better placed to provide global, enterprise level optimisations - Since similar messages and interactions can be identified much easier as people are looking at it.
  • Contracts provide very well defined, technical acceptance criteria which can be applied to automated testing very easily.
  • Non-development managers and senior managers in structured companies can identify with this method much easier.
  • Requires a joint design activity up-front to establish the form of the contract and solution.
  • Requires enough big picture thinking to effectively establish the inter-departmental contracts.
  • Not well understood or appreciate by the majority of purist agile developers who are often not concerned with the bigger picture.
  • Less scope to evolve the contracts, so worse for more fluid organisations where the business process is not known up-front.


The above non-exhaustive list of pros and cons should help guide the development and/or architecture teams on when to use which method. One day I hope to add metric to this set, such as using a multivariate model to  evaluate companies against this. It would be interesting to see if the community at large already has a similar way to define this. So drop me a comment if you do.

Sunday, 2 September 2012

The great, smoking pause...

As is often the case when I consult in the city [of London], I find my commute sucking up a large proportion of my day. In this instance, I lose almost two extra hours in productive time, which leaves me with little time to blog about anything.
I still have to finish my XP (2nd edition) review and also introduce some elements of process optimisation too. So if interested, stay tuned for that.

Also, to answer some questions sent to me recently, I am going to be comparing contract-first and code-first methods of developing service interfaces.

Fingers crossed I find time to properly write these up.