[fdo-dev] Assertions

[Greg Boone]

Hi Mateusz,

Since you are writing the PostGIS provider within the GenericRDBMS
framework we expect to be able to build and test the PostGIS provider in
the same manner and style as the MySQL and ODBC providers. This means we
expect you to write unit tests for the PostGIS provider in a CppUnit
style framework. 

>From our perspective, the build team are users as much as our external
clients such as MapGuide. The build team will building the provider in
Debug mode and executing the unit tests in Debug mode on a daily basis.
It is critical that all tests be able to be executed without asserting
or throwing an unhandled exception and all errors reported through
standard CppUnit error handling/reporting mechanisms.

The above 2 paragraphs deal with the newly developing PostGIS 'provider'
code base. As for any modifications you plan for existing GenericRDBMS
libraries such as RDBI, we expect that existing coding standards (as
seen in the existing subversion files) be followed. If Asserts are not
used in these components now then please do no introduce that behavior
in new code being submitted.

Thanks,

Greg

-----Original Message-----
From: Mateusz Loskot [mailto:mateusz at loskot.net] 
Sent: Monday, August 14, 2006 6:43 PM
To: dev at fdo.osgeo.org
Subject: Re: [fdo-dev] Assertions

Greg Boone wrote:
> I am not sure what you mean by equality.

I asked if FDO project considers intention of assertions and
exceptions the same.
If it's true, I can't agree. They behave *similar* but intentionally
they are very different constructions of a programming language.
Both are also distinguished in C++ Standard:

Chapter 19/2:
"The following subclauses describe components for reporting several
kinds of exceptional conditions, documenting program assertions, and a
global variable for error number codes, as summarized in Table 25."

next section explains assertions as follows:

19.2 Assertions [lib.assertions]
1 Provides macros for documenting C++ program assertions, and for
disabling the assertion checks.

This clearly says assertions =/= exceptions.

> All I am saying is that  generally, FDO does not throw assertions 
> (except the CPPUNIT unit test ASSERT macros).

Asserts in Unit Test are different story.
They are tests with similar logic to assert() macro
but with different behaviour (without stopping program execution).

> This is because:
> 
> 1) Assertions only are executed only in Debug

This idea is based on strong foundation (see below) and it is perfectly
correct as long as users (not developers) do not run debug release of
software.

> and do not provide any contextual error information to our users in a
>  production environment

This is true, because assertions are not intended to provide any useful
information to user, but to component developer.

> 2) Assertions on Windows cause the execution of code to halt and 
> force the user to intervene.

This is quite a common behavior of assert() macro. If assertions are
enabled and tested expression is false, the error message is (usually)
send to and calls abort() function (mostly). So, assertions do
not provide graceful recovery from errors

> This cause some difficulty in automating the execution of Debug unit 
> tests in a CPPUNIT style framework

I don't use CppUnit, but if this framework uses assert() macro to do
unit test checks, then this is an obvious bug in the CppUnit.
But I'm 99% sure they do not use assert() macro to test unit
assumptions.


Please, let me to list some important differences:

1. Assertions

a) Used *only* in development phase

b) Check pre-/post-conditions and invariants in *private* code,
on implementation level.

c) Test for things with very high unlikelihood to occur,
and when they occur, this always mean serious bug in application.

d) Provide some *comments* and feedback to developers
team (*not to user*). Asserts are

e) To state that are supposed to be *always* true

f) To indicate points the execution that are not supposed to
reach, like default clause of some switch statements.

g) Debug code and help to localize problems without further step-by-step
debugging (again, asserts are for developers, not users)

h) Comment and document logically impossible situations, inline.

i) keep application correct

2. Excepsion

a) Used in release phase

b) Used to check parameters that come from users, parameters
passed to public interface.

c) Enable users to gracefully recover from errors and give users freedom
to decide what errors to handle and to set custom severities.

d) To catch problems that might occur, that are expected to occur
under some conditions.

j) keep application robust

h) satisfy invariants even if errors occur and prevent run-time
errors from causing program/system/environment instability.

Certainly, there are situations where assertions may cause troubles,
or they should be used very carefully, AFAIK in Windows NT services. But
these are rather exceptions from the rule.

Assertion is one of the main weapon in Design By Contract
philosophy:
http://www.c2.com/cgi/wiki?DesignByContract

The rule of thumb of assertions usage is hould be:
"The more assertions look tedious and redundant, the
more appreciated they are and the more information they provide."

I'm not trying to write a book or complete manual, but I'm
only presenting my reasoning.

Nevertheless, I'm going to keep using assertions
in PostGIS provider.

Best regards
-- 
Mateusz Loskot
http://mateusz.loskot.net

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe at fdo.osgeo.org
For additional commands, e-mail: dev-help at fdo.osgeo.org