phobos/docsrc/cppdbc.d

Ddoc

$(COMMUNITY D's Contract Programming vs C++'s,

	Many people have written me saying that D's Contract Programming
	(DbC) does not add anything that C++ does not already support.
	They go on to illustrate their point with a technique for doing DbC in
	C++.
	<p>

	It makes sense to review what DbC is, how it is done in D,
	and stack that up with what each of the various C++ DbC techniques
	can do.
	<p>

	Digital Mars C++ adds
	<a href="../ctg/contract.html">extensions to C++</a>
	to support DbC, but they are not covered here because they are not
	part of standard C++ and are not supported by any other C++ compiler.

<h2>Contract Programming in D</h2>

	This is more fully documented in the D
	<a href="dbc.html">Contract Programming</a> document.
	To sum up, DbC in D has the following characteristics:

	$(OL 

	$(LI The $(I assert) is the basic contract.
	)

	$(LI When an assert contract fails, it throws an exception.
	Such exceptions can be caught and handled, or allowed to
	terminate the program.
	)

	$(LI Classes can have $(I class invariants) which are
	checked upon entry and exit of each public class member function,
	the exit of each constructor, and the entry of the destructor.
	)

	$(LI Assert contracts on object references check the class
	invariant for that object.
	)

	$(LI Class invariants are inherited, that means that a derived
	class invariant will implicitly call the base class invariant.
	)

	$(LI Functions can have $(I preconditions) and $(I postconditions).
	)

	$(LI For member functions in a class inheritance hierarchy, the
	precondition of a derived class function are OR'd together
	with the preconditions of all the functions it overrides.
	The postconditions are AND'd together.
	)

	$(LI By throwing a compiler switch, DbC code can be enabled
	or can be withdrawn from the compiled code.
	)

	$(LI Code works semantically the same with or without DbC
	checking enabled.
	)

	)

<h2>Contract Programming in C++</h2>

<h3>The $(TT assert) Macro</h3>

	C++ does have the basic $(TT assert) macro, which tests its argument
	and if it fails, aborts the program. $(TT assert) can be turned
	on and off with the $(TT NDEBUG) macro.
	<p>

	$(TT assert) does not know anything about class invariants,
	and does not throw an exception when it fails. It just aborts
	the program after writing a message. $(TT assert) relies on
	a macro text preprocessor to work.
	<p>

	$(TT assert) is where explicit support for DbC in Standard C++
	begins and ends.

<h3>Class Invariants</h3>

	Consider a class invariant in D:

----------
class A
{
    $(B invariant)() { ...contracts... }

    this() { ... }	// constructor
    ~this() { ... }	// destructor

    void foo() { ... }	// public member function
}

class B : A
{
    $(B invariant)() { ...contracts... }
    ...
}
----------

	To accomplish the equivalent in C++ (thanks to Bob Bell for providing
	this):

$(CCODE
template<typename T>
inline void check_invariant(T& iX)
{
#ifdef DBC
    iX.invariant();
#endif
}

// A.h:

class A {
    public:
#ifdef DBG
       virtual void invariant() { ...contracts... }
#endif
       void foo();
};

// A.cpp:

void A::foo()
{
    check_invariant(*this);
    ...
    check_invariant(*this);
}

// B.h:

#include "A.h"

class B : public A {
    public:
#ifdef DBG
	virtual void invariant()
	{   ...contracts...
	   A::invariant();
	}
#endif
       void bar();
};

// B.cpp:

void B::barG()
{
    check_invariant(*this);
    ...
    check_invariant(*this);
}
)

	There's an additional complication with $(TT A::foo()). Upon every
	normal exit from the function, the $(TT invariant()) should be
	called.
	This means that code that looks like:

$(CCODE
int A::foo()
{
    ...
    if (...)
	return bar();
    return 3;
}
)

	would need to be written as:

$(CCODE
int A::foo()
{
    int result;
    check_invariant(*this);
    ...
    if (...)
    {
	result = bar();
	check_invariant(*this);
	return result;
    }
    check_invariant(*this);
    return 3;
}
)

	Or recode the function so it has a single exit point.
	One possibility to mitigate this is to use RAII techniques:

$(CCODE
int A::foo()
{
#if DBC
    struct Sentry {
       Sentry(A& iA) : mA(iA) { check_invariants(iA); }
       ~Sentry() { check_invariants(mA); }
       A& mA;
    } sentry(*this);
#endif
    ...
    if (...)
	return bar();
    return 3;
}
)

	The #if DBC is still there because some compilers may not
	optimize the whole thing away if check_invariants compiles to nothing.

<h2>Preconditions and Postconditions</h2>

	Consider the following in D:

----------
void foo()
    in { ...preconditions... }
    out { ...postconditions... }
    body
    {
	...implementation...
    }
----------

	This is nicely handled in C++ with the nested Sentry struct:

$(CCODE
void foo()
{
    struct Sentry
    {   Sentry() { ...preconditions... }
	~Sentry() { ...postconditions... }
    } sentry;
    ...implementation...
}
)

	If the preconditions and postconditions consist of nothing
	more than $(TT assert) macros, the whole doesn't need to
	be wrapped in a $(TT #ifdef) pair, since a good C++ compiler will
	optimize the whole thing away if the $(TT assert)s are turned off.
	<p>

	But suppose $(TT foo()) sorts an array, and the postcondition needs
	to walk the array and verify that it really is sorted. Now
	the shebang needs to be wrapped in $(TT #ifdef):

$(CCODE
void foo()
{
#ifdef DBC
    struct Sentry
    {   Sentry() { ...preconditions... }
	~Sentry() { ...postconditions... }
    } sentry;
#endif
    ...implementation...
}
)

	(One can make use of the C++ rule that templates are only
	instantiated when used can be used to avoid the $(TT #ifdef), by
	putting the conditions into a template function referenced
	by the $(TT assert).)
	<p>

	Let's add a return value to $(TT foo()) that needs to be checked in
	the postconditions. In D:

----------
int foo()
    in { ...preconditions... }
    out (result) { ...postconditions... }
    body
    {
	...implementation...
	if (...)
	    return bar();
	return 3;
    }
----------

	In C++:

$(CCODE
int foo()
{
#ifdef DBC
    struct Sentry
    {   int result;
	Sentry() { ...preconditions... }
	~Sentry() { ...postconditions... }
    } sentry;
#endif
    ...implementation...
    if (...)
    {   int i = bar();
#ifdef DBC
	sentry.result = i;
#endif
	return i;
    }
#ifdef DBC
    sentry.result = 3;
#endif
    return 3;
}
)

	Now add a couple parameters to $(TT foo()). In D:

----------
int foo(int a, int b)
    in { ...preconditions... }
    out (result) { ...postconditions... }
    body
    {
	...implementation...
	if (...)
	    return bar();
	return 3;
    }
----------

	In C++:

$(CCODE
int foo(int a, int b)
{
#ifdef DBC
    struct Sentry
    {   int a, b;
	int result;
	Sentry(int a, int b)
	{   this->a = a;
	    this->b = b;
	    ...preconditions...
	}
	~Sentry() { ...postconditions... }
    } sentry(a,b);
#endif
    ...implementation...
	if (...)
	{   int i = bar();
#ifdef DBC
	    sentry.result = i;
#endif
	    return i;
	}
#ifdef DBC
	sentry.result = 3;
#endif
	return 3;
}
)

<h2>Preconditions and Postconditions for Member Functions</h2>

	Consider the use of preconditions and postconditions for a
	polymorphic function in D:

----------
class A
{
    void foo()
	in { ...Apreconditions... }
	out { ...Apostconditions... }
	body
	{
	    ...implementation...
	}
}

class B : A
{
    void foo()
	in { ...Bpreconditions... }
	out { ...Bpostconditions... }
	body
	{
	    ...implementation...
	}
}
----------

	The semantics for a call to $(TT B.foo()) are:

	$(UL 
	$(LI Either Apreconditions or Bpreconditions must be satisfied.)
	$(LI Both Apostconditions and Bpostconditions must be satisfied.)
	)

	Let's get this to work in C++:

$(CCODE
class A
{
protected:
    #if DBC
    int foo_preconditions() { ...Apreconditions... }
    void foo_postconditions() { ...Apostconditions... }
    #else
    int foo_preconditions() { return 1; }
    void foo_postconditions() { }
    #endif

    void foo_internal()
    {
	...implementation...
    }

public:
    virtual void foo()
    {
	foo_preconditions();
	foo_internal();
	foo_postconditions();
    }
};

class B : A
{
protected:
    #if DBC
    int foo_preconditions() { ...Bpreconditions... }
    void foo_postconditions() { ...Bpostconditions... }
    #else
    int foo_preconditions() { return 1; }
    void foo_postconditions() { }
    #endif

    void foo_internal()
    {
	...implementation...
    }

public:
    virtual void foo()
    {
	assert(foo_preconditions() || A::foo_preconditions());
	foo_internal();
	A::foo_postconditions();
	foo_postconditions();
    }
};
)

	Something interesting has happened here. The preconditions can
	no longer be done using $(TT assert), since the results need
	to be OR'd together. I'll leave as a reader exercise adding
	in a class invariant, function return values for $(TT foo()),
	and parameters
	for $(TT foo()).

<h2>Conclusion</h2>

	These C++ techniques can work up to a point. But, aside from
	$(TT assert), they are not standardized and so will vary from
	project to project. Furthermore, they require much tedious
	adhesion to a particular convention, and add significant clutter
	to the code. Perhaps that's why it's rarely seen in practice.
	<p>

	By adding support for DbC into the language, D offers an easy
	way to use DbC and get it right. Being in the language standardizes
	the way it will be used from project to project.

<h2>References</h2>

	Chapter C.11 introduces the theory and rationale of
	Contract Programming in
	<a href="http://www.amazon.com/exec/obidos/ASIN/0136291554/classicempire">
	Object-Oriented Software Construction
	</a><br>
	Bertrand Meyer, Prentice Hall
	<p>

	Chapters 24.3.7.1 to 24.3.7.3 discuss Contract Programming in C++ in
	<a href="http://www.amazon.com/exec/obidos/ASIN/0201700735/classicempire">
	The C++ Programming Language Special Edition
	</a><br>
	Bjarne Stroustrup, Addison-Wesley
	<p>

)

Macros:
	TITLE=D's Contract Programming vs C++'s
	WIKI=CppDbc