Prev: logging into site using form validation http components
Next: Windows priorities with runtime.exec
From: Tom Anderson on 6 Jun 2010 09:21
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
From: Patricia Shanahan on 6 Jun 2010 09:53
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?
>

Assuming by "superfluous comments" you mean comments that do not
contribute to describing the contract, and that "everything that should
be documented" includes the contract, this is a tautology.

I agree that "everything that should be documented" includes the
contract. However, I think interface documentation often needs
explanation of the interface's intended use. Those comments are not
superfluous - they are a proper part of the documentation, but not contract.

For example, the entire contract for Runnable is the existence of a
"void run()" method. The discussion of its intended use in conjunction
with threads is not superfluous - the interface would make no sense
without it - but is not part of the contract.

Patricia
From: Lew on 6 Jun 2010 09:58
On 06/06/2010 08:49 AM, Stefan Ram wrote:
> What do you deem to be the difference between the documentation
> and the contract of an interface?

The contract is what is promised, including promises of what will go wrong if
certain idioms or rules are not followed. For example, it's part of the
contract of java.util.HashMap that if the base type 'equals()' and
'hashCode()' are inconsistent so will be your results.

The documentation is what tells you what the contract is. It's like the
difference between a number and a numeral.

> 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.

Both forms are documentation; they both express precisely the exact same
identical contract. They are just different ways of writing the same thing.

> 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?

No, what you get is a stripped-down form of the documentation for the contract.

Documentation is the expression of the contract. You are asking what is the
difference between a description and an idea. There are many ways to describe
the same idea. There are many ways to document the same contract.

They are connected ideas, in that the contract is unenforceable unless
documented. Whether you say "counter() always returns a positive int" or
"@returns int > 0", the contract is the same, but omit both and there is no
contract for that clause. But either expression, whether "English" or "math"
(both are English, but hey, it's your distinction), refers to the same
contract clause.

--
Lew
From: Eric Sosman on 6 Jun 2010 10:29
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(a)ieee-dot-org.invalid
From: Arne Vajhøj on 6 Jun 2010 11:07
On 06-06-2010 08:49, 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?

Java does not support true contracts in the language itself.

So we have to rely on a description in English.

English is good enough for most practical purposes.

Do you need something more formal, then there are
other languages that supplies that (typical a language
describing the requirements and some subset of Ada
for implementation).

Arne
 |  Next  |  Last
Pages: 1 2 3
Prev: logging into site using form validation http components
Next: Windows priorities with runtime.exec