C++ assert best practices

Thursday November 17th, 2011

This blogpost is about best practices in using assert in C++.

For C++, the assert() macro can be used by including the cassert header file. In C it is defined in the assert.h file.

For me, an assertion is documentation that reason about how the design and the code should work. They are pre-conditions, post-conditions and loop invariants that the programmer make up to document expectations for a programs execution. It is the programmers contract with his design understanding.

As such they are a very important understanding for how the program work. If an assert fires and you do not agree with it, do not just remove it. However, make sure that the reasoning in the assert and the surrounding comments (design documentation) are correct. If you are unsure about what the reasoning is, it should be brought up for discussion. Otherwise you easily end up in a situation in where programmers understands and develops the code opposed to one another. It is hardly a good thing for the program code if the programmers thwarts each other.

Best Practices

• Don't use assert for error handling. It is not intended for this. It has nothing to do with error handling or exception handling at all.
• Assert can be used as a kind of unit test mechanism, but they are not intended for that. We should not use them as alternative for unit tests.
• Always write surrounding comments explaining why the assert is inserted - what it guards against (the invariant) or what design it "protects". Also describe the most likely causes for why the assert has triggered. The explanations should guide the programmer to correct his code that are causing the assert.
• It might be a good idea to write your initials or other contact information so that other programmers can contact you if discussion is needed.
• assert(false) may be used as an alternative for "not implemented", but this must be documented in surrounding comments.
• Use NDEBUG define to compile away, i.e. ignore, all asserts. This is recommended only for release builds.

A major advantage of using asserts is that when an assert is triggered it is detected immediately and directly, rather than causing problems later through often obscure side-effects. Since an assertion failure usually reports the code location, one can often pin-point the cause without further debugging. In some systems, e.g Windows, the assert will be shown in a dialog window with buttons that allow you to ignore the assert, i.e. the program continues, or open/start the debugger with the assert line of code in focus. In other systems, e.g. Unix/Linux, the assert will abort the program and trigger a core dump.

Temporarily turning off asserts?

However if you get an assert it may be in a piece of code that is totally unrelated to the task at hand. Should you spend time immediately to fix the problem that the assert is telling you about? Well, if you can you should definitely do it. But often, you do not have enough understanding of the code surrounding the assert or the responsible developer is unavailable for discussion. In this case the assertion, becomes an obstruction for your task in hand. It is indeed annoying to have to click Ignore to several assert-windows popping up. It would be nice if you at runtime can turn off assertions temporarily. This may be possible if you wrap and use your own assert macro instead of the built-in assert() macro. The wrapper may be guarded by a if-statement checking a global variable that you can turn on/off for whether you want assertions to be shown or not. If you want can also output the assert to a log file.

Note that this is different than setting/defining the NDEBUG macro that compiles away all the asserts. Using NDEBUG will not make it possible for you to turn asserts on/off at runtime. NDEBUG is only recommended when compiling release builds.

More (February 2014):

• Use of asserts, by John Regehr, Embedded in Academia,  February 2, 2014.

More (December 2013):

• Code Contracts is the next coding practice you should learn and use, by Patrick Smaccia, December 18, 2013. See also the Reddit debate.

More (November 2012):

• Assert Statements Shine Light Into Dark Corners, by Andrew Koenig, Dr. Dobbs, November 1^st.

Sources and More:

• http://en.wikipedia.org/wiki/Assertion_(computing)
• http://www.stanford.edu/~pgbovine/programming-with-asserts.htm
• http://stackoverflow.com/questions/1081409/why-should-i-use-asserts
• http://stackoverflow.com/questions/419406/are-assertions-always-bad
• http://drdobbs.com/blogs/java/228701655 (Assertations vs. Exceptions)
• http://www.artima.com/weblogs/viewpost.jsp?thread=54469 (What Can We Do About Unprovable Errors?)
• http://cnicholson.net/2009/02/stupid-c-tricks-adventures-in-assert