Using Assertion Checking

(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[])
    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):


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.



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” ).

Why are we here?

A lofty question, and one that I am unwilling to answer. But I think I can answer “Why is this clog here?”

After many years of having no formal writing outlet, I finally realized that I needed a place where my thoughts could coalesce into tangible form; in this case, words. I came to this realization while testing out our new wiki at work (very neat, definitely give it a look-see if you are at all interested in that sort of thing). I was examining its “blog” capabilities, and thought, “Hey, I could do this, it might even be kinda neat.” That started the wheels of my mind turning, and its logic flowed to the inevitable conclusion: Why not start my own personal “blog”?

But first, what the heck IS a “blog”? Indeed, just what is this bastard child supposed to be? Originally, (and I suppose we all know this by now) “blog” came as a short-hand for “web-log”. This was (as near as I can tell) supposed to be a form of online journal, published in electronic form using that new-fangled technology, The WebTM. Unfortunately, it seems this short-hand form of web log has stuck, so we are left with a throw back view of electronic publishing from the 1990s.

Being different, I called this a clog. The beauty is leaving the precise definition of what exactly a clog is up to you. It could be Chris’ Log, or Captain’s Log, or simply the thing that is backing the Internet pipes up. Whatever it may be to you, this is where I will be detailing what projects I’m working on, reflecting on experiences and musings that I may have, along with a general interest in everything around me.

Welcome to the clog.