Re: documentation versus contract
On Sun, 6 Jun 2010, Stefan Ram wrote:
What do you deem to be the difference between the documentation
and the contract of an interface?
Sure, sometimes the documentation is written in English and
the contract in math, so:
documentation: Please note that counter() always is positiv.
contract: counter() > 0.
But this distinction, based on the language, is superficially.
If we strip the documentation of an interface from all
superfluous comments and verbose tutorial-style
introductions, and include everything that should be
documented, what we get is the contract of this interface?
Pretty much.
As an example, if we look at Collection.toArray:
Object[] toArray()
Returns an array containing all of the elements in this collection. If
this collection makes any guarantees as to what order its elements are
returned by its iterator, this method must return the elements in the
same order.
The returned array will be "safe" in that no references to it are
maintained by this collection. (In other words, this method must allocate
a new array even if this collection is backed by an array). The caller is
thus free to modify the returned array.
This method acts as bridge between array-based and collection-based APIs.
Returns:
an array containing all of the elements in this collection
I'd say the contract defined here as the following points:
1. There is an instance method called 'toArray' which takes no parameters
and returns an array of Object.
2. Every object that is an element of the collection will be in the array.
3. If the collection has an order over its elements, the objects in the
array will be in that order.
4. The array will not be referred to by the collection after the method
returns.
In addition to those contractual points, the documentation contains some
non-contractual information: explanation of the implications of point 4,
and the observation about the method being a bridge between arrays and
collections.
This contract doesn't define what 'element' means; for it to be
meaningful, that must be defined elsewhere.
I note that there's nothing in there that forbids the array from
containing objects which are not elements of the collection. In practice,
that goes without saying, but in a properly-written specification, it
would be made explicit.
tom
--
In-jokes for out-casts