Re: documentation versus contract
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