CSC/ECE 517 Fall 2007/wiki3 2 bp

Programming by Contract

Purpose of this Wiki

This wiki page was created to address the following assignment:

In class, we had some difficulty coming up with good examples of programming by contract. Find some concise ones that illustrate the principle well, and are accessible to a general audience of programmers.

Overview

Programming by Contract originated with the Eiffel programming language. ¹ It is a technique for designing software systems in such a way that all the pieces meet certain obligations to each other. If all obligations are correctly met, then the system as a whole will work correctly.

The obligations are defined in terms of suppliers (components that offer a method that can be invoked) and clients (components that invoke those methods). Suppliers must provide the service they are contracted to provide (known as a postcondition), and clients must respect the restrictions of the supplier (known as a precondition).

It is important to note that programming by contract is more than a design approach. It can be enforced by the language itself to ensure that all code is written with an understanding of the contract (as opposed to simply specifying the assumed contract obligations in a comment at the top of a method).

Examples

Real World Examples

Examples in this section are based around real world metaphors and do not rely on programming specific concepts such as classes, methods, etc.

Example taken from http://en.wikipedia.org/wiki/Design_by_contract

Take the process of going on holiday, for example. Bertrand wants to spend two weeks in Florida. He books the
holiday through DBC Holidays Inc., who specialise in U.S. package holidays. When he makes the booking 
(collaboration #1), Bertrand is the client and DBC Holidays are the supplier. DBC Holidays then arrange flights 
through Assertair Corp. (collaboration #2), and book a room at the Precondition Plaza Hotel in Miami 
(collaboration #3). In collaboration #2, DBC Holidays are the client and Assertair is the supplier, and in 
collaboration #3, the hotel is the supplier. And the chain of collaborations goes deeper and deeper (e.g., who 
does Assertair pay to service their jets?)

If any link in this chain of collaborations breaks, then the result could be that Bertrand's holiday is ruined. 
It's vital, therefore, that every player in the collaboration does what they're supposed to do. In any 
collaboration, client and supplier have certain obligations. These obligations (or "responsibilities", if you 
like) fall into three distinct types:

   1. Things that the supplier promises to do as part of the service it offers to the client (e.g., Assertair 
      promises DBC Holidays that Bertrand will be in Miami at a certain date and time)
   2. Things that the client promises to do before using the service (e.g., DBC Holidays must ensure that 
      Bertrand has his passport and tickets when he checks in for his flight)
   3. Things that the supplier promises will always be true no matter what happens (e.g., The airline will 
      always have adequate insurance to cover any accident)

Things that the supplier promises to do as part of the service are described as a special kind of rule called a
postcondition. The postcondition tells the client what will be true if the service is executed correctly (e.g., 
"your customer will be in Miami by 15:30 on June 8").

If Bertrand turns up at the check-in desk without his passport, of course, then the airline can't live up to its 
side of the contract: he will not be allowed to board the plane without it. A rule that the client must satisfy 
before using a service is called a precondition.

A rule that states what must always be true is called an invariant. If the airline doesn't have adequate 
insurance then nobody is going anywhere!

---

Example from http://archive.eiffel.com/doc/manuals/technology/contract/

	Obligations	Benefits
Client	Be at the Santa Barbara airport at least 5 minutes before scheduled departure time. Bring only acceptable baggage. Pay ticket price.	Reach Chicago.
Supplier	Bring customer to Chicago.	No need to carry passenger who is late, has unacceptable baggage, or has not paid ticket price.

Programming Based Examples

Examples in this section use terms which are more specific to programming, defining themselves in terms of classes, methods, and pseudocode. In keeping with the goal of having the examples be accessible to the general audience of programmers, examples using exotic/rare programming languages were excluded.

Example in Java from: http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html

In this example a Stack class is defined in Java as a supplier of certain methods. It's contractual obligations are specified in the comments of each method as either requirements (contractual obligations on the client) or ensure statements (assurances about the state of the system after the method is invoked. i.e. preconditions)

class Stack {  // supplier
  Object[] data = null;

  int top = -1;
  int n = 0;

  public Stack(int n)
    // require n>0;
  {
    this.n = n;
    data = new Object[n];
  }

  public void push(Object o)
    // require top<(n-1);
    // ensure top==o;
    // ensure top = old top + 1;
  {
    top++;
    data[top] = o;
  }

class Main { // client
  public static void main(String[] args) {
    Stack s = new Stack(10);
    s.push("Apple");
  }
}

References

The overview and examples above were drawn from the following sources:

http://en.wikipedia.org/wiki/Design_by_contract

http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html

http://archive.eiffel.com/doc/manuals/technology/contract/