Re: documentation versus contract
On 6/6/2010 8:49 AM, 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?
It seems to me that the documentation -- Javadoc, tutorials,
theses, whatever -- is part of the contract, not something separate
from it. Some parts of the contract can be expressed in Java, some
are beyond Java's expressive power. To understand a contract, you
must read both the Java and the non-Java parts.
Examples of contracts not expressible in Java abound: Override
both or neither of equals() and hashCode(), always do Swing things
on the Event Dispatch Thread, and so on. There's nothing in the
Java language itself that prohibits
@Override
public int compareTo(Thing that) {
return (int)(System.currentTimeMillis() % 3 - 1);
}
.... but it clearly violates the "contract" of Comparable<Thing>.
I do not think you can separate the natural-language "compareTo()
returns results consistent with a total ordering" from the Java-
expressible part "compareTo() is public, takes a Thing parameter,
returns an int, and throws no checked exceptions." Both are part of
the contract; both must be understood and observed (and relied upon).
I don't think the distinction between English (Italian, Dutch, ...)
and mathematical notation is especially relevant. The non-Java parts
of the contract will be expressed in whatever ways their writer thinks
will best communicate to the likely audience. He may choose to use
mathematical notation and/or concepts ("@return least prime factor"),
he may choose other jargon ("@throws UnstableMoleculeException if the
1,1,3 ionizations of the Atoms are incompatible"), he may choose other
vehicles ("<a href=http://www.erewhon.org/buymybook.asp>"). It doesn't
really matter: He's trying to describe the contract by whatever means
he can, using both Java and non-Java constructs.
--
Eric Sosman
esosman@ieee-dot-org.invalid