Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-22T03:25:22Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditions]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check [http://expertiza.csc.ncsu.edu/wiki/index.php/CSC/ECE_517_Fall_2011/ch6_6a_pc#Preconditions preconditions], [http://expertiza.csc.ncsu.edu/wiki/index.php/CSC/ECE_517_Fall_2011/ch6_6a_pc#Postconditions postconditions], and [http://expertiza.csc.ncsu.edu/wiki/index.php/CSC/ECE_517_Fall_2011/ch6_6a_pc#Invariants invariants] when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly [http://en.wikipedia.org/wiki/Assertion_(computing) assertions] can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where [http://www.cprogramming.com/tutorial/exceptions.html normal error handling] is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) [http://www.ece.cmu.edu/~koopman/des_s99/sw_testing/#concepts Correctness] - system's ability to perform its job according to the specification and 2) [http://en.wikipedia.org/wiki/Robustness_%28computer_science%29 Robustness] - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. [http://en.wikipedia.org/wiki/Type_system#Static_typing Static typing], for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly [http://msdn.microsoft.com/en-us/library/ee787088.aspx Garbage collection] helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, Reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. [http://en.wikipedia.org/wiki/Subtype_polymorphism Polymorphism] also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a [http://expertiza.csc.ncsu.edu/wiki/index.php/CSC/ECE_517_Fall_2011/ch6_6a_pc#Preconditions precondition] that must be satisfied by the consumer of the routine. And each feature ends with [http://expertiza.csc.ncsu.edu/wiki/index.php/CSC/ECE_517_Fall_2011/ch6_6a_pc#Postconditions postconditions] which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from [http://www.amazon.com/Object-Oriented-Design-Using-Java-Skrien/dp/0072974168 Skrien]):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. [http://expertiza.csc.ncsu.edu/wiki/index.php/CSC/ECE_517_Fall_2011/ch6_6a_pc#Languages_with_Native_Support Eiffel]). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when [http://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming) Inheritance] and [http://en.wikipedia.org/wiki/Polymorphism_in_object-oriented_programming polymorphism] are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

[http://en.wikipedia.org/wiki/Defensive_programming Defensive programming] on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

[http://msdn.microsoft.com/library/z1zx9t92 C#] 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref><ref>http://c2.com/cgi/wiki?HaltingProblemDiscussions</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T05:06:46Z

Mabanz: /* Contract and Inheritance */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly [http://en.wikipedia.org/wiki/Assertion_(computing) assertions] can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when [http://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming) Inheritance] and [http://en.wikipedia.org/wiki/Polymorphism_in_object-oriented_programming polymorphism] are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

[http://en.wikipedia.org/wiki/Defensive_programming Defensive programming] on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

[http://msdn.microsoft.com/library/z1zx9t92 C#] 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref><ref>http://c2.com/cgi/wiki?HaltingProblemDiscussions</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T05:06:17Z

Mabanz: /* Contract and Inheritance */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly [http://en.wikipedia.org/wiki/Assertion_(computing) assertions] can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when [http://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming) Inheritance] and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

[http://en.wikipedia.org/wiki/Defensive_programming Defensive programming] on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

[http://msdn.microsoft.com/library/z1zx9t92 C#] 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref><ref>http://c2.com/cgi/wiki?HaltingProblemDiscussions</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T05:03:34Z

Mabanz: /* Comparison with Defensive Programming */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly [http://en.wikipedia.org/wiki/Assertion_(computing) assertions] can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

[http://en.wikipedia.org/wiki/Defensive_programming Defensive programming] on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

[http://msdn.microsoft.com/library/z1zx9t92 C#] 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref><ref>http://c2.com/cgi/wiki?HaltingProblemDiscussions</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:47:53Z

Mabanz: /* Assertions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly [http://en.wikipedia.org/wiki/Assertion_(computing) assertions] can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

[http://msdn.microsoft.com/library/z1zx9t92 C#] 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref><ref>http://c2.com/cgi/wiki?HaltingProblemDiscussions</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:46:11Z

Mabanz: /* Languages with Native Support */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

[http://msdn.microsoft.com/library/z1zx9t92 C#] 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref><ref>http://c2.com/cgi/wiki?HaltingProblemDiscussions</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:45:03Z

Mabanz: /* Static Checking */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref><ref>http://c2.com/cgi/wiki?HaltingProblemDiscussions</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:41:02Z

Mabanz: /* Static Checking */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].<ref>http://www.efgh.com/math/impossible.htm</ref>

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:37:46Z

Mabanz: /* Static Checking */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the [http://en.wikipedia.org/wiki/Halting_problem halting problem].

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:36:11Z

Mabanz: /* Static Checking */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java<ref>http://www.eecs.umich.edu/~bchandra/courses/papers/Flanagan_ESC.pdf</ref> offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:35:23Z

Mabanz: /* Static Checking */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts<ref>http://msdn.microsoft.com/en-us/magazine/hh335064.aspx</ref> and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:34:17Z

Mabanz: /* Languages with Native Support */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.<ref>http://msdn.microsoft.com/en-us/library/dd264808.aspx</ref>

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:31:36Z

Mabanz: /* Languages with Native Support */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.<ref>http://www.eiffel.com/developers/design_by_contract_in_detail.html</ref>

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:29:37Z

Mabanz: /* Languages with Native Support */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> <ref> http://java.sun.com/developer/technicalArticles/JavaLP/assertions/ </ref> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to [http://www.eiffel.com/ Eiffel]; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:27:22Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.<ref>http://mindprod.com/jgloss/assertions.html</ref> Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:21:08Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s.<ref>Meyer, Bertrand: Design by Contract, Technical Report TR-EI-12/CO, Interactive Software Engineering Inc., 1986</ref> Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an <code>assert</code> statement in Java or <code>Contract.Requires</code> statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.
For example, suppose you have the following code in your method:
<pre>
void foo() {
for (...) {
if (...)
return;
}
// Execution should never reach this point!!!
}
</pre>

Rather than just leaving a comment, you could add an assert statement as follows:
<pre>
void foo() {
for (...) {
if (...)
return;
}
assert false; // Execution should never reach this point!
}
</pre>
This will throw an AssertionError when the program reaches that unexpected point of execution. This enables the programmer to catch any irregularities in the code at any stage of development, making the process of debugging very easy. Similarly assertions can be used to verify the preconditions, postconditions and class invariants in a method. You can assert that preconditions hold good at the start of the method, and that postcondition and class invariant hold good at the end of method execution. This ensures that contract is always being satisfied by both the supplier and the client. Of course having assert statements incurs overhead, for instance, if we have to perform some clean-up in case the post condition is not met. So most of the programming languages provide a means to disable the assertions at runtime. E.g in Java, you could use: <code> -disableassertions or -da switch</code>.

Note that assertions do not allow for recovery from errors; an assertion failure will normally halt the program's execution abruptly. Hence it would be unwise to use assertions where normal error handling is necessary. Assertions should only be used to document logically impossible situations and discover programming errors.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:09:29Z

Mabanz: /* Languages with Native Support */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language.<ref>http://www.eiffel.com/developers/design_by_contract.html</ref> When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:08:37Z

Mabanz: /* Invariants */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: a linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:08:04Z

Mabanz: /* Preconditions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:07:26Z

Mabanz: /* Static Checking */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== <div id="staticChecking">Static Checking</div> ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:06:45Z

Mabanz: /* Languages with Native Support */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== <div id="nativeSupport">Languages with Native Support</div> ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:06:05Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase [[ #reliability | software reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:05:44Z

Mabanz: /* Software Reliability */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software [[ #reliability | reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== <div id="reliability">Software Reliability</div> ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:05:08Z

Mabanz: /* Assertions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software [[ #reliability | reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== <div id="assertions">Assertions</div> ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:04:27Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditions | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software [[ #reliability | reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T04:03:40Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software [[ #reliability | reliability]] by creating explicit specifications for each method. Contract violations can be detected early on using [[ #assertions | assertions]] or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among others have [[ #nativeSupport | native support]] for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform [[ #staticChecking | static checking]] at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T03:39:06Z

Mabanz: /* Preconditions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the [http://www.eiffel.com/ Eiffel programming language].

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T03:37:02Z

Mabanz: /* Invariants */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="invariants">Invariants</div> ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T03:36:41Z

Mabanz: /* Postconditions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== <div id="postconditions">Postconditions</div> ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T03:34:50Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariants | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T03:34:28Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain [[ #postconditions | postconditions]] are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a [[ #invariant | class invariant]]. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T03:31:13Z

Mabanz: /* Preconditions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== <div id="preconditions">Preconditions</div> ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T03:30:00Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain [[ #preconditons | preconditons]] are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T02:53:24Z

Mabanz: /* Invariants */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A [http://en.wikipedia.org/wiki/Class_invariant class invariant] is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T02:52:40Z

Mabanz: /* Postconditions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A [http://en.wikipedia.org/wiki/Postcondition postcondition] is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T02:49:13Z

Mabanz: /* Preconditions */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A [http://en.wikipedia.org/wiki/Precondition precondition] is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T02:46:42Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier".<ref>http://www.cs.usfca.edu/~parrt/course/601/lectures/programming.by.contract.html</ref> The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T02:42:25Z

Mabanz:

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

== Topical References ==

<references/>

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T02:40:26Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by [http://en.wikipedia.org/wiki/Bertrand_Meyer Bertrand Meyer] in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-18T02:39:34Z

Mabanz: /* Introduction */

== Introduction ==

[http://en.wikipedia.org/wiki/Design_by_contract Programming by contract] is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

CSC/ECE 517 Fall 2011

2011-11-18T02:07:42Z

Mabanz:

[[Link title]]
*[[CSC/ECE 517 Fall 2011/ch1 1a ms]]

*[[CSC/ECE 517 Fall 2011/ch1 1a cs]]

*[[CSC/ECE 517 Fall 2011/ch1 1a ri]]

*[[CSC/ECE 517 Fall 2011/ch1 1a lj]]

*[[CSC/ECE 517 Fall 2011/ch1 1b sa]]

*[[CSC/ECE 517 Fall 2011/ch1 1b ds]]

*[[CSC/ECE 517 Fall 2011/ch1 1b tj]]

*[[CSC/ECE 517 Fall 2011/ch1 1c cm]]

*[[CSC/ECE 517 Fall 2011/ch1 1c sj]]

*[[CSC/ECE 517 Fall 2011/ch1 1c ka]]

*[[CSC/ECE 517 Fall 2011/ch1 1d sr]]

*[[CSC/ECE 517 Fall 2011/ch1 1e vs]]

*[[CSC/ECE 517 Fall 2011/ch1 1e aa]]

*[[CSC/ECE 517 Fall 2011/ch1 1a sc]]

*[[CSC/ECE 517 Fall 2011/ch1 1e dm]]

*[[CSC/ECE 517 Fall 2011/ch1 1e an]]

*[[CSC/ECE 517 Fall 2011/ch1 1e sa]]

*[[CSC/ECE 517 Fall 2011/ch1 1e lm]]

*[[CSC/ECE 517 Fall 2011/ch1 1g vn]]

*[[CSC/ECE 517 Fall 2011/ch1 1f rs]]

*[[CSC/ECE 517 Fall 2011/ch1 1f sv]]

*[[CSC/ECE 517 Fall 2011/ch1 1g jn]]

*[[CSC/ECE 517 Fall 2011/ch1 1h ps]]

*[[CSC/ECE 517 Fall 2011/ch1 1e sm]]

*[[CSC/ECE 517 Fall 2011/ch1 1i zf]]

*[[CSC/ECE 517 Fall 2011/ch1 1g rn]]

*[[CSC/ECE 517 Fall 2011/ch1 1i cl]]

*[[CSC/ECE 517 Fall 2011/ch1 1d ss]]

*[[CSC/ECE 517 Fall 2011/ch1 1i lj]]

*[[CSC/ECE 517 Fall 2011/ch1 1h hs]]

*[[CSC/ECE 517 Fall 2011/ch1 1d gs]]

*[[CSC/ECE 517 Fall 2011/ch1 2b ns]]

*[[CSC/ECE 517 Fall 2011/ch1 2b jp]]

*[[CSC/ECE 517 Fall 2011/ch1 2a av]]

*[[CSC/ECE 517 Fall 2011/ch2 2f jm]]

*[[CSC/ECE 517 Fall 2011/ch2 2e ad]]

*[[CSC/ECE 517 Fall 2011/ch2 2e kt]]

*[[CSC/ECE 517 Fall 2011/ch2 2e gp]]

*[[CSC/ECE 517 Fall 2011/ch1 2b qu]]

*[[CSC/ECE 517 Fall 2011/ch2 2c bs]]

*[[CSC/ECE 517 Fall 2011/ch1 2c rs]]

*[[CSC/ECE 517 Fall 2011/ch1 2a ca]]

*[[CSC/ECE 517 Fall 2011/ch1 2b rv]]

*[[CSC/ECE 517 Fall 2011/ch2 2c ds]]

*[[CSC/ECE 517 Fall 2011/ch2 2b sa]]

*[[CSC/ECE 517 Fall 2011/ch2 2f mm]]

*[[CSC/ECE 517 Fall 2011/ch2 2f vh]]

*[[CSC/ECE 517 Fall 2011/ch2 2e ps]]

*[[CSC/ECE 517 Fall 2011/ch3 3a oe]]

*[[CSC/ECE 517 Fall 2011/ch3 3h rr]]

*[[CSC/ECE 517 Fall 2011/ch3 3h ss]]

*[[CSC/ECE 517 Fall 2011/ch3 4b js]]

*[[CSC/ECE 517 Fall 2011/ch3 4b ms]]

*[[CSC/ECE 517 Fall 2011/ch4 4b ds]]

*[[CSC/ECE 517 Fall 2011/ch4 4i aa]]

*[[CSC/ECE 517 Fall 2011/ch4 4i sd]]

*[[CSC/ECE 517 Fall 2011/ch4 4d mt]]

*[[CSC/ECE 517 Fall 2011/ch4 4d ls]]

*[[CSC/ECE 517 Fall 2011/ch4 4d ch]]

*[[CSC/ECE 517 Fall 2011/ch4 4c ap]]

*[[CSC/ECE 517 Fall 2011/ch4 4h sv]]

*[[CSC/ECE 517 Fall 2011/ch4 4e cl]]

*[[CSC/ECE 517 Fall 2011/ch4 4e gs]]

*[[CSC/ECE 517 Fall 2011/ch4 4a ga]]

*[[CSC/ECE 517 Fall 2011/ch4 4f sl]]

*[[CSC/ECE 517 Fall 2011/ch4 4i js]]

*[[CSC/ECE 517 Fall 2011/ch4 4f ss]]

*[[CSC/ECE 517 Fall 2011/ch4 4c dm]]

*[[CSC/ECE 517 Fall 2011/ch4 4g as]]

*[[CSC/ECE 517 Fall 2011/ch4 4g nv]]

*[[CSC/ECE 517 Fall 2011/ch4 4g ms]]

*[[CSC/ECE 517 Fall 2011/ch4 4h kp]]

*[[CSC/ECE 517 Fall 2011/ch4 4h as]]

*[[CSC/ECE 517 Fall 2011/ch4 4j fw]]

*[[CSC/ECE 517 Fall 2011/ch4 4f rs]]

*[[CSC/ECE 517 Fall 2011/ch4 4i lc]]

*[[CSC/ECE 517 Fall 2011/ch17 5b uo]]

*[[CSC/ECE 517 Fall 2011/ch17 5b br]]

*[[CSC/ECE 517 Fall 2011/ch5 5d he]]

*[[CSC/ECE 517 Fall 2011/ch5 6d ny]]

*[[CSC/ECE 517 Fall 2011/ch6 6d sk]]

*[[CSC/ECE 517 Fall 2011/ch6 6e ch]]

*[[CSC/ECE 517 Fall 2011/ch6 6b ss]]

*[[CSC/ECE 517 Fall 2011/ch6 6b ra]]

*[[CSC/ECE 517 Fall 2011/ch6 6c sj]]

*[[CSC/ECE 517 Fall 2011/ch6 6a am]]

*[[CSC/ECE 517 Fall 2011/ch6 6e zj]]

*[[CSC/ECE_517_Fall_2011/ch6 6e gm]]

*[[CSC/ECE 517 Fall 2011/ch6 6f jd]]

*[[CSC/ECE 517 Fall 2011/ch6 6f va]]

*[[CSC/ECE 517 Fall 2011/ch6 6c p]]

*[[CSC/ECE 517 Fall 2011/ch6 6e gm]]

*[[CSC/ECE 517 Fall 2011/ch6 6c sm]]

*[[CSC/ECE 517 Fall 2011/ch18 6a sc]]

*[[CSC/ECE 517 Fall 2011/ch18 6d na]]

*[[CSC/ECE 517 Fall 2011/ch6 6a pc]]

*[[trial]]

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T07:40:02Z

Mabanz: /* Comparison with Defensive Programming */

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T07:39:04Z

Mabanz: /* Languages with Native Support */

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value when declaring a postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Code Contracts also support class invariants. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>. The class invariant method is called after the execution of every public method in the class.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Static Checking ===

In addition to runtime contract checking, some libraries offer static checking at compile time as well. These tools can catch contract violations without even running the code. C# code contracts and the Extended Static Checker (ESC) for Java offer just that. Static analysis has theoretic limitations due to it being equivalent to the halting problem.

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T07:24:51Z

Mabanz: /* C# */

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

''' C# '''

C# 4.0 has native support for code contracts via the System.Diagnostics.Contract library. Preconditions are introduced with a call to <code>Contract.Requires</code> and postconditions with a call to <code>Contract.Ensures</code>. Code contracts also allow the programmer to access the return value in the postcondition.

<pre>
public void Add(int num1, int num2)
{
Contract.Requires(num1 > 0);
Contract.Requires(num2 > 0);

return num1 + num2;

Contract.Ensures(Contract.Result<int>() > 0);
}
</pre>

Class invariants are also supported. An invariant method must be decorated with the <code>ContractInvariantMethod</code> attribute and contain only calls to <code>Contract.Invariant</code>.

<pre>
[ContractInvariantMethod]
protected void ObjectInvariant ()
{
Contract.Invariant ( this.y >= 0 );
Contract.Invariant ( this.x > this.y );
...
}
</pre>

=== Runtime Checking ===

=== Static Checking ===

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T07:10:53Z

Mabanz: /* Eiffel */

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

''' Eiffel '''

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

=== C# ===

=== Runtime Checking ===

=== Static Checking ===

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T07:10:13Z

Mabanz: /* Languages with Native Support */

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

=== Eiffel ===

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

=== C# ===

=== Runtime Checking ===

=== Static Checking ===

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T07:09:20Z

Mabanz:

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

=== Runtime Checking ===

=== Static Checking ===

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T07:09:00Z

Mabanz: /* Introduction */

6a (was 5c). Lecture 18, Programming by contract. My notes for Lecture 18 are largely taken from 20-year-old articles by Bertrand Meyer. The principles are timeless, but there are undoubtedly new embellishments that would provide better background to the topics discussed in the lecture. Write a narrative, generally following the lecture organization, that explains programming by contract in more detail.

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance. Languages such as Eiffel and C# (via the System.Diagnostics.Contract library) among other have native support for contracts. C# Code Contracts and the Extended Static Checker (ESC) for Java have the ability to perform static checking at compile time to determine if a possible run-time contract exception can occur. This feature is limited due to the fact that it is equivalent to the halting problem.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

=== Runtime Checking ===

=== Static Checking ===

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T06:54:17Z

Mabanz: /* Introduction */

6a (was 5c). Lecture 18, Programming by contract. My notes for Lecture 18 are largely taken from 20-year-old articles by Bertrand Meyer. The principles are timeless, but there are undoubtedly new embellishments that would provide better background to the topics discussed in the lecture. Write a narrative, generally following the lecture organization, that explains programming by contract in more detail.

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract aims to increase software reliability by creating explicit specifications for each method. Contract violations can be detected early on using assertions or similar means. A contract violation indicates a potential bug in the code. Many languages allow these assertions to be used when debugging and turned off in production to increase performance.

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

=== Runtime Checking ===

=== Static Checking ===

CSC/ECE 517 Fall 2011/ch6 6a pc

2011-11-17T06:45:00Z

Mabanz: /* Introduction */

6a (was 5c). Lecture 18, Programming by contract. My notes for Lecture 18 are largely taken from 20-year-old articles by Bertrand Meyer. The principles are timeless, but there are undoubtedly new embellishments that would provide better background to the topics discussed in the lecture. Write a narrative, generally following the lecture organization, that explains programming by contract in more detail.

== Introduction ==

Programming by contract is a paradigm used in software design that was first introduced by Bertrand Meyer in the 1980s. Programming by contract defines a contractual relationship between the caller of a method and the method itself. It is analogous to a business relationship where both parties must meet certain obligations but also receive benefits. In terms of programming by contract, the caller is know as the "client" and the method being called is known as the "supplier". The client must ensure that certain preconditons are met before calling the supplier. The supplier benefits from not having to check the arguments itself. The supplier in return must ensure that certain postconditions are met. The client benefits from knowing that it received what it expected. Another concept, also part of programming by contract, is a class invariant. A class invariant is a condition that must be true throughout the lifetime of each instance of that class.

Programming by contract

== Terminology ==

=== Preconditions ===

A precondition is a condition that must be true prior to calling a method for which it is defined. Preconditions bind the caller of that method, that is, it is the responsibility of the caller to ensure that the preconditions are satisfied. The method is not responsible, nor expected, to check the preconditions. The output from the method is not defined for the case where the preconditions are violated. In that case the method could crash the system, go into an infinite loop, or do nothing at all.

The <code>require</code> block constitutes a precondition in the Eiffel programming language.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= are23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Postconditions ===

A postcondition is a condition that must be true after execution of the method for which it is defined. Postconditions bind the method itself. The method is responsible for ensuring that these conditions are met. The caller of the method is guaranteed that the postconditions will hold if the original preconditions were satisfied when calling the method.

The <code>ensure</code> block constitutes a postcondition in Eiffel.

<pre>
set_hour (a_hour: INTEGER)
-- Set `hour' to `a_hour'
require
valid_argument: 0 <= a_hour and a_hour <= 23
do
hour := a_hour
ensure
hour_set: hour = a_hour
end
</pre>

=== Invariants ===

A class invariant is a condition that must hold true throughout the lifetime of an object. It is a condition imposed on the class itself rather than a method of that class. Class invariants are often checked before and after the execution of each method in that class. An object found in a state where the invariant does not hold, would indicate a bug in the system.

An example of a class invariant: A linked list has an instance variable <code>length</code> that stores the number of nodes in the list. <code>length</code> should always equal the actual number of nodes in the list.

<pre>
class LinkedList {
private Node head;
private int length; // length stores a cached version of the number of nodes. It should always equal the actual number of nodes.

public LinkedList() {
head = null;
length = 0;
}

public getLength() {
return length;
}

public void Add(int value) {
Node n = new Node(value);

if(head == null) {
head = n;
}
else {
Node current = head;

while(current.getNext() != null) {
current = current.getNext();
}
current.setNext(n);
n.setPrevious(current);
}
length++;
}

/* other methods omitted */
}
</pre>

Along with Preconditions and Postconditions, class invariants provide another means to write good code. Class invariants come to the fore when we look at guidelines for writing methods. We typically have two types of methods : accessors, that simply retrieve a value and modifiers, that modify the object on which they are called. There is an important guideline for modifier methods to observe if they are to do their jobs well: "Public methods should always keep objects in a well-formed state.".

Here, well-formed state seems like a very subjective term. A good way to specify what makes objects of a class well-formed is to list the class invariants. A class invariant is a statement about the state of objects of the class between public method calls.

The Following example illustrates the usage and importance of class invariants.
For the LinkedList class, the following could be the class invariants:

#The value of instance variable <code>length</code> is always equal to the number of elements on the list.
#The <code>next</code> instance variable of the last node on the list must have null or some other special placeholder object as its value.

With the first invariant, it is clear that we have to initialize <code>length</code> to 0 in the constructor and update it appropriately in <code> add </code> and <code> remove </code> methods. This will prevent any bugs from creeping into the code and in case they did, debugging becomes much simpler.
Similarly the second invariant makes sure that the linked list is well terminated. Otherwise a user traversing the list could end up writing at illegal memory location. Hence class invariants are valuable tools in writing good code.

'''How do we identify class invariants?'''

Since class invariants describe the state of an object between method calls, one easy way to identify them is to look at the instance variables of the class, since instance variables hold the state of an object. This has an implication that, many instance variables can lead to many Invariants and hence make it hard to debug. One should look at the trade-off between performance and the number of class invariants when deciding on adding instance variables.
For instance, in the LinkedList example, not having <code>_length</code> instance variable would help us reduce the number of invariants, but this would mean that user will have to traverse the list each time he needs to count the number of items on the list.

=== Assertions ===

It is useful to check preconditions, postconditions, and invariants when debugging code. A violation of which constitutes a bug in the system. This can be accomplished using an assert statement in Java or Contract.Requires statement in C# 4.0. These programming features can be used to alert the programmer of bugs in development and can be turned off in production.

== Software Reliability ==
A major concern in software design is Reliability, which depends on two factors: 1) Correctness - system's ability to perform its job according to the specification and 2) Robustness - handling abnormal conditions. Reliability is especially important in Object oriented software because of the additional complexity imposed by Reusability. Some of the common problems encountered when writing software include:
* System failure - CPU crash, Disk/Memory access errors, Network errors
* Invalid input data - Out of range data, Bad file name,etc.
* Programming errors - Memory leaks, Buffer overruns, etc.

There are many programming language features that help tackle these issues. Static typing, for example, is a major help for catching inconsistencies before they have had time to become bugs. Similarly Garbage collection helps to remove the specter of devious memory management errors. Various software design methodologies also come handy when dealing with complex software. For instance, reusability itself can help eliminate lots of bugs, if we are reusing existing code that has already been thoroughly tested and deployed. Polymorphism also helps in handling issues related to maintainability by reducing the size of the code and making it more elegant. But in a large and complex software involving multiple developers, we need a more systematic approach of specifying and implementing object-oriented software elements and their interactions. This is exactly what "Programming by contract" promises to do.

=== Programming by contract ===
Basically programming by contract creates a contract between the software developer and software user, which are referred to as the supplier and the consumer. Every feature, or method, starts with a precondition that must be satisfied by the consumer of the routine. And each feature ends with postconditions which the supplier guarantees to be true after it is executed(if and only if the preconditions were met). Consider the following example of a static Intersect() method on a Set object (Quoted from Skrien 4.6):

<pre>
public static Set intersect(Set s1, Set s2)
Precondition: s1 and s2 are not null.
Postcondition:
Returns a Set with the common elements of s1 and s2, if s1 and s2 are not null.
If s1 or s2 is null, an IllegalArgumentException is thrown.
</pre>

Note here that this documentation is not overly specific about the implementation nor is it very general and vague. This can be stated concisely as a guideline:
"The external documentation for a method should be sufficiently specific to exclude implementations that are unacceptable but sufficiently general to allow
all implementations that are acceptable". are

Also, the above contract does not mention anything about the behavior of the method when preconditions are not satisfied. This is Meyer’s non-redundancy principle: "Under no circumstances shall the body of a routine ever test for the routine’s precondition". This implies that if the preconditions are not met, the behavior of the method is undefined (it could crash, throw an exception, or run in an infinite loop, etc.).

(Does it fit here?)
In essence, this theory suggests associating a specification with every software element. These specifications (or contracts) govern the interaction of the element with the rest of the world. This is different from having a formal specification in that the specification language is embedded in the design and programming language (e.g. Eiffel). This makes it possible to use a single notation and a single set of concepts throughout the software life cycle, and since these are modeled based on the programming language itself, it provides a great deal of clarity about the requirements at each stage of software development.

=== Contract and Inheritance ===
An important implication of Programming by Contract is when Inheritance and polymorphism are involved. Subtype polymorphism means: "If S is a subtype of T,then any term of type S can be safely used in a context where a term of type T is expected". In case of object oriented programming, type is defined by a class and inheritance enables us to define subtypes of a class (If Base class defines a type, the Derived class becomes a subtype). In this situation, the Derived class should fully honor the Base class contract. Consider the following example:

Suppose you are given a class List, that has a public interface: <code> insert(Item const& x) </code>.
And suppose you have to implement a new class SortedList, and provide insert method with the same signature. Isn't is obvious that SortedList be made a subclass of List and override the insert() method?. The answer is no!.

To decide whether we can override the List::insert() method, we will have to look at the Contract promised by this method. Suppose the base class insert() method has advertised its contract as "Promises a copy of Item will be inserted somewhere within this List". In this case the derived class can override this, since this is a weak post-condition which can be strengthened in the derived class. So the derived class insert() can say that "Promises a copy of Item will be inserted in the sorted order within this List" and no contract is broken.

Suppose, instead the Base class method has a strong post condition: "Promises a copy of Item will be inserted at the end of this List". Then the derived class cannot override this, since derived class cannot guarantee that the Item will be inserted at the end, hence a breach of Contract.

'''So why bother with all this Contract business?'''

Consider in the above example (strong post-condition case), suppose the derived class breaches the contract and overrides insert() anyway. Now a user who was using the List::insert() method assumes that the items are added at the end, i.e sorted based on time of insertion. But suppose he accidentally calls SortedList::insert() through the base class List pointer, then the Item would be inserted somewhere in-between based on the value it contains, rather than the time of insertion. This will surely introduce hard-to-find bugs in the code, which is the problem this principle was designed to solve. Liskov's substitution principle that deals with the Base-Derived relationship can be rephrased based on this understanding:

It is acceptable to subclass B from a class A, if for every public method with identical signatures in A and B,
#Pre-conditions for B's method are no stronger than preconditions for A's method
#Post-conditions for B's method are no weaker than postconditions for A's method

== Comparison with Defensive Programming ==
Restating the crux of "Programming by contract": "The supplier class guarantees postconditions of its methods as long as client guarantees that preconditions of those methods are met". This implies that if the client fails to satisfy the preconditions, the behavior of supplier is undefined, meaning it could result in an Exception being thrown, or a system crash.

Defensive programming on the other hand, augments this guideline as - "Try to make your methods do something appropriate in all cases so that there are no preconditions". You know errors are almost certainly going to occur and illegal input is going to be given to methods, so make sure that your methods can defend against such input by doing something explicit in a way that is helpful to the user of those methods.

However, this approach could introduce major performance hit. For instance, consider a method that performs binary search on an integer array. A precondition for such a method is that the array is sorted. To eliminate this precondition, the binary search method could first check the array to see if it is sorted and, if not, throw an exception. However, in that case the method’s efficiency is reduced from O(log n) to O(n), where n is the array size.

=== Advantages of Programming by Contract ===

=== When not to use Programming by Contract ===
Asserts and "by contract" specifications catch programmer errors not run-time errors! (Add more details)

== Languages with Native Support ==

Design by contract is central to Eiffel; it is built into the language. When using inheritance to override a method, one may only weaken the preconditions not strengthen them. Thus a call to any method of a subclass is guaranteed to meet the preconditions of the parent class. Conversely, postconditions can only be strengthened in an overridden method so that the results guaranteed by the parent class will still be met by the base class.

Eiffel uses the <code>require</code> keyword to introduce preconditions and the <code>ensure</code> keyword to introduce postconditions. If a precondition or postcondition is violated, an exception is thrown. Exception handling is not used for control flow or for invalid data input. In Eiffel, one can handle an exception using the <code>rescue</code> keyword. Inside the exception handling section, the <code>retry</code> keyword may be used to execute the method again.

<pre>
connect_to_server (server: SOCKET)
-- Connect to a server or give up after 10 attempts.
require
server /= Void and then server.address /= Void
local
attempts: INTEGER
do
server.connect
ensure
connected: server.is_connected
rescue
if attempts < 10 then
attempts := attempts + 1
retry
end
end
</pre>

=== Runtime Checking ===

=== Static Checking ===