1. Design by Contract
Fall 2016 Version

2. Motivation for Modular Design
Separation of concerns
Independent development by team members
Bug localization
Ease of evolution and maintenance

3. Design by Contract (DBC)
Also known as programming-to-the-interface
Articulated clearly only in the 1980s
Design-by-contract has become the standard policy governing separation of concerns across modern software engineering
This is how software components are really used…

4. Idea of a Contract
There are component providers (or implementers) and users (or clients)
Implementers and clients communicate through contracts
Contracts “hide information” by design, because they are irrelevant for clients
Contracts may be formal or informal, but they must be understandable to clients so hidden info cannot be used!

5. Contract for an Operation
A requires clause (precondition) that characterizes the responsibility of the caller
Not all operations will have a requires clause.
An ensures clause (postcondition) that characterizes the responsibility of the code that implements that operation
Implementer assumes the requires clause.
Ensures clause is guaranteed only if the caller satisfies the requires clause!

6. Why Use Ensures Clauses?
Without them, how can a user know what the operation does?
Names alone can’t tell the whole story! More on this later.
Don’t want users to have to look at code! Defeats the very idea of using design by contract.

7. Why Use Requires Clauses?
Efficiency!
In the absence of requires clauses, implementations will have to do error checking.
Those checks will happen every time an operation is called, whether or not checks are needed!

8. Simple Example Example function private static int func (int x) {…}
Suppose for func to work properly x must be between 1 and 4.
If the code for func did the checking, it would perform a check even on the following call!
int ans = func(3);
For the above call, neither the caller nor the code needs to do any checking!

9. Simple Example Example function private static int func (int x) {…}
Suitable requires clause for func
1 <= x <= 4

10. 1. Contract: Requires clause
Write a suitable requires clause for the factorial function below.
private static long factorial(short i) {… }

11. Another Example
Operation (or method) to binary search if an item is in an array
Requires that the array is sorted
Ensures that it returns true if the item is in the array and false otherwise
Why should the search code not check the requires clause?

12. Another Example
Operation (or method) to binary search if an item is in an array
Requires that the array is sorted
Ensures that it returns true if the item is in the array and false otherwise
Why should the search code not check the requires clause?
It would take linear time to check that the array is sorted, though it’d take only log time to search!

13. Yet Another Example Integer division operation
Does it have an (implicit) requires clause?
Why?

14. Yet Another Example Integer division operation
Does it have an (implicit) requires clause?
Why?
Yes, divisior should not be 0!
Division operator doesn’t check, because then divisions would be slow!
So it’s the division user’s responsibility, a requires clause!

15. 2. Contract: Requires clause
Function compute is going to access the array “a” at “index” and do some computation. Write a suitable requires clause.
private static int compute
(int[] a, int index) {… }

16. Last little bit
In general, requires clauses avoid unnecessary code and improve code efficiency
However, end users may not understand responsibilities such as requires clauses, so error checking needs to be coded!
Example: User, input a choice between 1 and 10.

17. Role of Contracts What does this method call do? How do you know?
double a, b; …
double c = sqrt (a*a + b*b, 0.001);
12 November November 2018
OSU CSE

18. Example of a Contract /** * ...
x number to take the square root of
epsilon allowed relative error
the approximate square root of x
* x > 0  and  epsilon > 0
<pre>
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 * </pre>
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

19. Example of a Contract A Java comment that starts with the symbols /**
* ...
x number to take the square root of
epsilon allowed relative error
the approximate square root of x
* x > 0  and  epsilon > 0
<pre>
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 * </pre>
 */
private static double sqrt(double x,
double epsilon)
A Java comment that starts with the symbols
/**
is called a Javadoc comment; it goes before the method header.
12 November November 2018
OSU CSE

20. Javadoc
The standard documentation technique for Java is called Javadoc
You place special Javadoc comments enclosed in /** … */ in your code, and the javadoc tool generates nicely formatted web-based documentation from them
12 November November 2018
OSU CSE

21. APIs
The resulting documentation is known as the API (application programming interface) for the Java code to which the Javadoc tags are attached
Example API: OSU CSE components at:
12 November November 2018
OSU CSE

22. The word interface has two related but distinct meanings:
APIs
The resulting documentation is known as the API (application programming interface) for the Java code to which the Javadoc tags are attached
The word interface has two related but distinct meanings:
a unit of Java code that contains Javadoc comments used to produce documentation
the resulting documentation
12 November November 2018
OSU CSE

23. Example of a Contract
/**
* ...
x number to take the square root of
epsilon allowed relative error
the approximate square root of x
* x > 0  and  epsilon > 0
<pre>
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 * </pre>
 */
private static double sqrt(double x,
double epsilon)
The Javadoc is needed for each formal parameter; you describe the parameter’s role in the method.
12 November November 2018
OSU CSE

24. Example of a Contract
/**
* ...
x number to take the square root of
epsilon allowed relative error
the approximate square root of x
* x > 0  and  epsilon > 0
<pre>
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 * </pre>
 */
private static double sqrt(double x,
double epsilon)
The Javadoc is needed if the method returns a value; you describe the returned value.
12 November November 2018
OSU CSE

25. Example of a Contract
The Javadoc introduces the precondition for the sqrt method.
/**
* ...
x number to take the square root of
epsilon allowed relative error
the approximate square root of x
* x > 0  and  epsilon > 0
<pre>
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 * </pre>
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

26. Example of a Contract
The Javadoc introduces the postcondition for the sqrt method.
/**
* ...
x number to take the square root of
epsilon allowed relative error
the approximate square root of x
* x > 0  and  epsilon > 0
<pre>
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 * </pre>
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

27. Example of a Contract
Javadoc comments may contain HTML-like tags; e.g., <pre> … </pre> means spacing and line-breaks are retained in generated documentation.
/**
* ...
x number to take the square root of
epsilon allowed relative error
the approximate square root of x
* x > 0  and  epsilon > 0
<pre>
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 * </pre>
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

28. 3. Contract Basics Which of the following statements are true?
Ensures clause is the responsibility of the operation (method) implementer
Requires clause is assumed by the implementer before the code
Requires clause is the responsibility of the caller
Ensures clause is assumed by the caller after the call

29. Abbreviated Javadoc For this course:
Code you see in these slides will not have the and formatting tags <pre>; plus, “keywords” in the Javadoc and mathematics will be bold-faced for easy reading
This allows you to focus on the contract content: the requires and ensures clauses themselves
12 November November 2018
OSU CSE

30. Example Contract (Abbreviated)
/**
* ...
* x > 0  and  epsilon > 0
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

31. Example Contract (Abbreviated)
/**
* ...
* x > 0  and  epsilon > 0
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x] }
 */
private static double sqrt(double x,
double epsilon)
This is the precondition, indicating that the arguments passed in for the formal parameters x and epsilon both must be positive before a client may call sqrt.
12 November November 2018
OSU CSE

32. Example Contract (Abbreviated)
/**
* ...
* x > 0  and  epsilon > 0
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x] }
 */
private static double sqrt(double x,
double epsilon)
The precondition is a statement about the models of the arguments;
here, it is a formal mathematical statement about mathematical reals.
12 November November 2018
OSU CSE

33. Example Contract (Abbreviated)
/**
* ...
* x > 0  and  epsilon > 0
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 */
private static double sqrt(double x,
double epsilon)
This is the postcondition, indicating that the return value from sqrt is non-negative and … what does the rest say?
12 November November 2018
OSU CSE

34. Example Contract (Abbreviated)
/**
* ...
* x > 0  and  epsilon > 0
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 */
private static double sqrt(double x,
double epsilon)
The first part of the postcondition here is written in mathematical notation; it is not program code! The second part — inside […] — is written in English.
12 November November 2018
OSU CSE

35. Using a Method Contract
A static method’s contract refers to its formal parameters, and (only if it returns a value, not void) to the name of the method (which stands for the return value)
To determine whether the precondition and postcondition are true for a particular client call:
The values of the arguments are substituted for the respective formal parameters
The value of the result returned by the method is substituted for the method name
12 November November 2018
OSU CSE

36. Reasoning: Tracing Tables
Code
State
y = 76.9
y = sqrt(4.0, 0.01);
y = 2.0
12 November November 2018
OSU CSE

37. Reasoning: Tracing Tables
Code
State
y = 76.9
z = 4.0
y = sqrt(z, 0.01);
y = 2.0
12 November November 2018
OSU CSE

38. Reasoning: Tracing Tables
From the contract of sqrt,
do we know that
y = 2.0
instead of
y = –2.0?
Code
State
y = 76.9
z = 4.0
y = sqrt(z, 0.01);
y = 2.0
12 November November 2018
OSU CSE

39. Reasoning: Tracing Tables
From the contract of sqrt,
do we know that
y = 2.0
instead of
y = ?
Code
State
y = 76.9
z = 4.0
y = sqrt(z, 0.01);
y = 2.0
12 November November 2018
OSU CSE

40. A Partly Informal Contract
/**
* ...
* x > 0  and  epsilon > 0
 * sqrt >= 0  and
 * [sqrt is within relative error epsilon
* of the actual square root of x]
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

41. A Formal Contract /** * ... * @requires * x > 0 and epsilon > 0
 * sqrt >= 0  and
 * |sqrt - x^(1/2)| / x^(1/2) <= epsilon
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

42. A Formal Contract
We can, in this formal setting, easily substitute 4.0 for x, 0.01 for epsilon, and either 2.0 or for sqrt … and is the ensures clause is true in either case? Yes!
/**
* ...
* x > 0  and  epsilon > 0
 * sqrt >= 0  and
 * |sqrt - x^(1/2)| / x^(1/2) <= epsilon
 */
private static double sqrt(double x,
double epsilon)
12 November November 2018
OSU CSE

43. Using contracts for reasoning
There are reasoning tools that can leverage formal contracts
The tools can check that client code does not violate preconditions
The tools can check implementation code does not violate postconditions
You will be exposed to one such tool in this course

44. Using Java “assert” statements
To localize bugs during development and debugging in Java, we can use “assert” statements in client or implementation code
Example: assert x > 0.0 : “Violation of precondition x > 0”;
This checking can be turned off (to avoid inefficiency in production software) using the “-ea” argument to the JVM

45. Resources Wikipedia: Design by Contract