(Thank you to Fred Chouinard and Steven Pigeon for feedback on this post many moons ago)

The goal of this article is to briefly explain assertion checking. It will describe what an assertion is, why we want to use them, when and where they should be used and some pitfalls to watch out for. It will close with a small example of how to enable them for the Java platform.

What is an Assertion

An assertion is a special operation that instructs the compiler to perform a particular test, and if it fails, to crash and dump debugging information to either a window or the console. The programmer must provide the test to the compiler, and each language that supports assertions has its own syntax:

Java: assert( answer == 42 );
C++: assert( answer == 42 );
Python: assert answer == 42 'The answer to Life the Universe and Everything is NOT 42!'

Using Assertions

By default in Java, assertion checking is disabled. You can enable assertion checking at run time by simply adding the option -enableassertions or -ea. You can also enable/disable system class assertions by using either the -esa or -dsa options respectively.

We will take a look at assertions first with a quick example in C++. By default asserting checking should be enabled with g++ (make sure that you do NOT #define NDEBUG and that -DNDEBUG is not passed to g++ when compiling the following program:

#include <iostream>
#include <cassert>

void printNumber(int number)
{
    assert(number > 4); // all numbers < 5 do not deserve to be printed!
    std::cout << number << " is a worthy number to print!" << std::endl;
}

int main(int c, char* argv[])
{
    printNumber(7);
    printNumber(3);
    return 0;
}

Execute the following command:

helium$ g++ ./assertion.cpp && ./a.out

And you should get the following output:

7 is a worthy number to print!
Assertion failed: (number > 4), function printNumber, file ./assertion.cpp, line 7.
Abort trap

Why should we use Assertions

Assertions can be an easy and effective way of documenting the implicit assumptions that a programmer makes in the code about the state of the program/application/system at a given point in execution. For example, take the following code snippet:

...
foo = bar.getFoo();
assert( foo > 4 ); // because a minimum of 5 is a sane value
...

In this example, the programmer will also add conditional code (if/else-if/else) to handle the “weird” condition should it arise. So why should we add an assertion check? Assertions allow programmers to specify “crashpoints” or very clear points in the code that will crash “artificially” (due to the assertion failing) and indicate sooner rather than later that the program/application/system is in a state that it should not be. This, in turn, speeds up debugging and error tracing during the integration and testing phases of development.

When should we use Assertions

Some people think that one should check conditions all the time, so debugging/testing with assertions active and releasing without them is a rather silly idea. People that think like this generally point out that if you think it’s important enough to test now, your code should not only always be checking that condition, but it should also handle the condition gracefully ( i.e. release resources, close files, etc). And this is absolutely correct. I would go further and suggest that assertions are a complementary practice to this that allows a programmer to document and provide explicit assumptions about the program/application/system state (that essentially cost nothing as they will be removed in production code). This in turn will speed up the identification of bad assumptions in the code rather than tracing back an error when it emerges further up the execution stack (either via an explicit mechanism such as an exception or via a “weird” bug).

Generally, the rule I follow is: if my code can/should recover from an unexpected state, use an if statement to test/handle the condition. If my code cannot recover from the unexpected state or is not expected to recover from it, I test the state/assumption with an assert. This makes debugging easier as the assertion will help localize the problem quickly within the code. Even when assertions are used, testing without them must always be done: Test as you Fly, Fly as you Test.

For a more detailed treatise on using assertions (within Java specifically, but most of the concepts are fairly generic): http://java.sun.com/j2se/1.4.2/docs/guide/lang/assert.html

Concurrency and Assertions

When we delve into the world of concurrent code, the use of assertions takes on an entirely new importance. In an environment where program/application/system state can change unexpectedly at any time, assertions provide a simple and effective way to identify where a programmer’s assumptions of the state is incorrect. This technique can be especially useful when complex interactions between code components are occurring in different places at the same time.

Pitfalls and Booby Traps

When testing a condition, it is very important that the test itself does not modify the state. An example of this would be calling a method on object A that modifies the state of object A. This will mean that the assert is a required part of the code logic and will break the code when removed. Another important consideration is the time to execute the assertion. If a test takes a long amount of time (where test execution time will be application specific) it will affect how the code runs, especially in a concurrent environment.

Summary

In summary, assertions are an important complementary tool for programmers that helps locate bad assumptions in their code more quickly during development and testing. They also help document these assumptions in an explicit way when they might not normally have been. Assertion tests must never alter program/application/system state. When using assertions, programmers must always remember to test with assertions disabled ( “Test as you Fly, Fly as you Test” ).