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.