Copyright (C) 1999-2001  Internet Software Consortium.
See COPYRIGHT in the source root or http://isc.org/copyright.html for terms.

$Id: DBC,v 1.5 2001/01/09 21:46:58 bwelling Exp $

Design By Contract

BIND 9 uses the "Design by Contract" idea for most function calls.

A quick summary of the idea is that a function and its caller make a
contract.  If the caller meets certain preconditions, then the
function promises to either fulfill its contract (i.e. guarantee a set
of postconditions), or to clearly fail.

"Clearly fail" means that if the function cannot succeed, then it will
not silently fail and return a value which the caller might interpret
as success.

If a caller doesn't meet the preconditions, then "further execution is
undefined".  The function can crash, compute a garbage result, fail silently,
etc.  Allowing the function to define preconditions greatly simplifies many
APIs, because the API need not have a way of saying "hey caller, the values
you passed in are garbage".

Typically, preconditions are specified in the functions .h file, and encoded
in its body with REQUIRE statements.  The REQUIRE statements cause the program
to dump core if they are not true, and can be used to identify callers that
are not meeting their preconditions.

Postconditions can be encoded with ENSURE statements.  Within the body of
a function, INSIST is used to assert that a particular expression must be
true.  Assertions must not have side effects that the function relies upon,
because assertion checking can be turned off.

