Design by Contract Fall 2016 Version

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

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…

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!

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!

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.

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!

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!

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

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

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?

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!

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

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!

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) {… }

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.

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 201812 November 2018 OSU CSE

Example of a Contract /** * ... * @param x number to take the square root of * @param epsilon allowed relative error * @return the approximate square root of x * @requires * x > 0  and  epsilon > 0  * @ensures <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 201812 November 2018 OSU CSE

Example of a Contract A Java comment that starts with the symbols /** * ... * @param x number to take the square root of * @param epsilon allowed relative error * @return the approximate square root of x * @requires * x > 0  and  epsilon > 0  * @ensures <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 201812 November 2018 OSU CSE

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 201812 November 2018 OSU CSE

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: http://cse.osu.edu/software/common/doc/ 12 November 201812 November 2018 OSU CSE

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 201812 November 2018 OSU CSE

Example of a Contract /** * ... * @param x number to take the square root of * @param epsilon allowed relative error * @return the approximate square root of x * @requires * x > 0  and  epsilon > 0  * @ensures <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 tag @param is needed for each formal parameter; you describe the parameter’s role in the method. 12 November 201812 November 2018 OSU CSE

Example of a Contract /** * ... * @param x number to take the square root of * @param epsilon allowed relative error * @return the approximate square root of x * @requires * x > 0  and  epsilon > 0  * @ensures <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 tag @return is needed if the method returns a value; you describe the returned value. 12 November 201812 November 2018 OSU CSE

Example of a Contract The Javadoc tag @requires introduces the precondition for the sqrt method. /** * ... * @param x number to take the square root of * @param epsilon allowed relative error * @return the approximate square root of x * @requires * x > 0  and  epsilon > 0  * @ensures <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 201812 November 2018 OSU CSE

Example of a Contract The Javadoc tag @ensures introduces the postcondition for the sqrt method. /** * ... * @param x number to take the square root of * @param epsilon allowed relative error * @return the approximate square root of x * @requires * x > 0  and  epsilon > 0  * @ensures <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 201812 November 2018 OSU CSE

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. /** * ... * @param x number to take the square root of * @param epsilon allowed relative error * @return the approximate square root of x * @requires * x > 0  and  epsilon > 0  * @ensures <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 201812 November 2018 OSU CSE

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

Abbreviated Javadoc For this course: Code you see in these slides will not have the Javadoc tags @param, @return, 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 201812 November 2018 OSU CSE

Example Contract (Abbreviated) /** * ... * @requires * x > 0  and  epsilon > 0  * @ensures  * 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 201812 November 2018 OSU CSE

Example Contract (Abbreviated) /** * ... * @requires * x > 0  and  epsilon > 0  * @ensures  * 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 201812 November 2018 OSU CSE

Example Contract (Abbreviated) /** * ... * @requires * x > 0  and  epsilon > 0  * @ensures  * 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 201812 November 2018 OSU CSE

Example Contract (Abbreviated) /** * ... * @requires * x > 0  and  epsilon > 0  * @ensures  * 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 201812 November 2018 OSU CSE

Example Contract (Abbreviated) /** * ... * @requires * x > 0  and  epsilon > 0  * @ensures  * 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 201812 November 2018 OSU CSE

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 201812 November 2018 OSU CSE

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

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

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 201812 November 2018 OSU CSE

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

A Partly Informal Contract /** * ... * @requires * x > 0  and  epsilon > 0  * @ensures  * 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 201812 November 2018 OSU CSE

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

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

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

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

Resources Wikipedia: Design by Contract http://en.wikipedia.org/wiki/Design_by_contract