Assertions — Use assertions (assert) for invariants (intro) - C Plus Plus

SECTION 1

Historical Context & Motivation

Software bugs have plagued computing since its earliest days, and the discipline of defensive programming emerged as a systematic response. Long before modern debuggers and unit testing frameworks existed, programmers needed a lightweight mechanism to verify that critical assumptions held true during execution. The concept of an assertion — a Boolean condition that the programmer believes must always be true at a particular point in the program — filled this gap. When an assertion fails, execution halts immediately, providing a clear signal that an invariant has been violated and the program's internal state is corrupt. This approach transforms silent, hard-to-diagnose bugs into loud, immediately detectable failures, which is one of the most powerful debugging strategies available.

1949 • Turing's Checking Assertions

Alan Turing proposed inserting "checking assertions" into programs so that the machine could verify that the programmer's reasoning was correct at key points during execution — an early precursor to the modern assert.

1969 • Hoare Logic & Formal Preconditions

C. A. R. Hoare published his axiomatic approach to program correctness, introducing the notion of preconditions, postconditions, and invariants as formal properties that assertions can enforce.

1978 • C Language assert Macro

The C standard library introduced the assert macro in <assert.h>, providing a portable, zero-overhead-in-release mechanism for runtime invariant checking. C++ inherited this macro directly.

2011 • C++11 static_assert

C++11 added static_assert for compile-time assertion checking, complementing the runtime assert macro and enabling type-level and template constraint verification before any code executes.

2020 • C++20 Contracts (Proposed)

The C++ standards committee explored contract-based programming with preconditions, postconditions, and assertion levels, aiming to formalize assertions as first-class language features rather than preprocessor macros.

The central question that assertions address is deceptively simple: How can a programmer make implicit assumptions explicit, and how can the runtime automatically detect when those assumptions are violated? Without assertions, a corrupted pointer or an out-of-range index might silently propagate through thousands of lines before manifesting as a crash or incorrect output, making the root cause nearly impossible to trace. Assertions collapse the distance between cause and symptom to zero.

SECTION 2

Core Principles & Definitions

Before diving into syntax, it is essential to understand the conceptual vocabulary that surrounds assertions. An invariant is a condition that must remain true throughout a specific scope of execution — for example, a sorted array must remain sorted after every operation in a binary search, or a pointer must be non-null before dereferencing. A precondition is a condition that must hold at the entry point of a function, while a postcondition must hold upon its return. Assertions serve as executable documentation for all three categories, turning logical guarantees into checked statements.

Invariant

A property that must always be true at a particular program point. Loop invariants, class invariants, and data-structure invariants are common categories.

Precondition

A condition that callers must satisfy before invoking a function. For example, a square-root function requires its argument to be non-negative.

Postcondition

A condition guaranteed by a function upon its return. After sorting, the output array must satisfy a[i] ≤ a[i+1] for all valid indices.

NDEBUG & Debug/Release

When the preprocessor macro NDEBUG is defined, all assert() calls compile to no-ops. This two-mode behavior allows zero-cost assertions in release builds.

Fail-Fast Philosophy

Assertions embody the principle that detecting a bug immediately at the point of violation is far better than letting corrupted state propagate silently through the system.

✦

KEY TAKEAWAY

Think of an assertion like a fuse in an electrical circuit. A fuse is not part of the circuit's normal operation — you never want it to blow — but if current exceeds the safe threshold, the fuse trips immediately and cuts power before any wiring melts. An assert works the same way: it is silent when your assumptions hold, but it halts the program the instant an invariant is violated, preventing catastrophic downstream damage.

SECTION 3

Visual Explanation — How assert Works at Runtime

The flowchart traces the two-stage decision process of assert(expr). First, the preprocessor checks whether NDEBUG is defined; if so, the entire assertion is compiled away. Otherwise, expr is evaluated at runtime: a true result continues execution silently, while a false result prints a diagnostic message (file, line, expression text) to stderr and calls abort() to terminate the process immediately.

The diagram above illustrates a crucial design decision: the dual-mode behavior of the assert macro. During development (debug builds), assertions actively guard your invariants and crash loudly when something goes wrong. In production (release builds), the preprocessor symbol NDEBUG causes the compiler to remove every assert call entirely, so there is zero runtime overhead. This means you should never place code with side effects inside an assertion — if you do, that code will silently disappear in release mode, changing your program's behavior.

SECTION 4

How assert Works Under the Hood

The Preprocessor Expansion

The assert macro is defined in the header <cassert> (or the C header <assert.h>). Although implementations vary across compilers, the macro conceptually expands into something equivalent to the following pseudo-expansion. Understanding this expansion clarifies why assertions behave as they do and what information is available when one fires.

CONCEPTUAL EXPANSION (DEBUG MODE)

assert(expr) \to ((expr) ? (void)0 : __assert_fail(#expr, __FILE__, __LINE__, __func__))

When NDEBUG is NOT defined, the macro evaluates expr. If true, the no-op (void)0 executes. If false, an implementation-specific function prints the stringified expression, file name, line number, and enclosing function name to stderr, then calls abort().

RELEASE MODE EXPANSION

assert(expr) → ((void)0)

When NDEBUG IS defined (typically via -DNDEBUG compiler flag), the macro expands to a no-op. The expression is never evaluated — no runtime cost, but also no invariant checking.

Typical Failure Output

When an assertion fails, the diagnostic message printed to stderr typically looks like: main.cpp:42: void processData(int*): Assertion `ptr != nullptr' failed. This message provides four critical pieces of information — the source file, the line number, the function name, and the literal text of the failed expression — which together allow a developer to locate the bug immediately without needing to run a debugger.

static_assert: Compile-Time Assertions

C++11 introduced static_assert, which evaluates a constant expression at compile time. Unlike the runtime assert macro, static_assert causes a compilation error if its condition is false. This is invaluable for verifying template parameters, type sizes (static_assert(sizeof(int) == 4, "int must be 4 bytes")), and other compile-time invariants. Because it operates at compile time, static_assert is unaffected by NDEBUG and always remains active.

⚠

Common Pitfall

Never place expressions with side effects inside assert(). For example, assert(initialize() == SUCCESS) is dangerous because initialize() will never be called in a release build. Instead, store the result first: auto result = initialize(); assert(result == SUCCESS);

SECTION 5

Classification of Invariants

Assertions are most powerful when applied systematically to the different categories of invariants that arise in software. Understanding where to place assertions requires recognizing the types of invariants your code maintains. The following diagram illustrates the three principal categories and their typical placement within a function or class.

The three columns show where to place assertions: preconditions at function entry, loop invariants inside loops, and postconditions before returning. The bottom panel shows a class invariant checker — a method that can be called from multiple points to verify the object's representation invariant.

Invariant Type	Where to Place	Example Assertion	What It Catches
Precondition	First line(s) of function body	`assert(denominator != 0);`	Caller violates function contract
Loop invariant	Top or bottom of loop body	`assert(lo <= hi);`	Off-by-one or divergent iteration
Postcondition	Just before return statement	`assert(is_sorted(v.begin(), v.end()));`	Function fails to establish its guarantee
Class (rep) invariant	End of constructors, mutating methods	`assert(size_ <= capacity_);`	Object enters an invalid state

Summary of invariant types and assertion placement

SECTION 6

Worked Example — Asserting Invariants in a Binary Search

Consider implementing a binary search function for a sorted vector. This is a classic algorithm where off-by-one errors are notoriously common, and assertions can catch them instantly during development. We will add assertions for the precondition (the array is sorted), the loop invariant (the search bounds remain valid), and the postcondition (the returned index actually contains the target).

Binary Search with Assertions

1
Step 1 — Include the Header and Define the Function Signature

Include <cassert> and <algorithm> at the top of the translation unit. Define the function as int binarySearch(const std::vector<int>& v, int target). The function returns the index of target if found, or -1 otherwise.

#include <cassert> and #include <algorithm>
2
Step 2 — Assert the Precondition

At the top of the function body, assert that the input vector is sorted. This is the precondition — the caller's responsibility. We write: assert(std::is_sorted(v.begin(), v.end())); Note that std::is_sorted is O(n), so this assertion has a performance cost. This is acceptable because assertions are disabled in release builds.

Precondition assertion: assert(std::is_sorted(v.begin(), v.end()));
3
Step 3 — Initialize Bounds and Assert the Loop Invariant

Initialize int lo = 0, hi = static_cast<int>(v.size()) - 1; and enter the search loop while (lo <= hi). At the top of each iteration, assert the loop invariant: assert(lo >= 0 && hi < static_cast<int>(v.size())); This catches any bound that escapes the valid index range.

Loop invariant: assert(lo >= 0 && hi < (int)v.size());
4
Step 4 — Perform the Search Logic

Compute int mid = lo + (hi - lo) / 2; (avoiding integer overflow). Compare v[mid] with target: if equal, proceed to the postcondition; if v[mid] < target, set lo = mid + 1; otherwise set hi = mid - 1.
5
Step 5 — Assert the Postcondition and Return

When the target is found at index mid, assert the postcondition before returning: assert(v[mid] == target); then return mid;. If the loop exits without finding the target, return -1. The three assertions together form a correctness net: if any step is buggy, the assertion fires at the earliest possible moment.

Postcondition: assert(v[mid] == target); return mid;

SECTION 7

Strengths and Limitations of assert

Strengths	Limitations
Zero runtime cost in release builds (compiled away via NDEBUG)	Disabled in release builds — cannot protect production code
Provides precise diagnostic: file name, line number, expression text	Calls abort(), which is abrupt — no stack unwinding, no cleanup
Serves as executable documentation of programmer intent	Cannot customize error messages (standard assert only)
Simple syntax — single macro, no framework needed	Not suitable for validating external input (use exceptions or error codes instead)
Catches bugs close to their source, reducing debugging time dramatically	Expressions with side effects inside assert introduce subtle release-mode bugs

Strengths versus limitations of the C/C++ assert macro

✦

WHEN TO USE ASSERT vs. EXCEPTIONS

Use assert for conditions that should never be false if the code is correct — these are programmer errors. Use exceptions or error codes for conditions that can legitimately fail at runtime — file-not-found, invalid user input, network timeouts. Think of it this way: an assertion failure means there is a bug in your code; an exception means the outside world did something unexpected.

SECTION 8

Connection to Advanced Testing & Contract Programming

The assert macro is the simplest form of invariant checking, but it represents just one point on a broad spectrum of techniques for ensuring program correctness. Understanding where assert fits in this spectrum helps you appreciate both its power and its proper scope. As you advance, you will encounter more sophisticated mechanisms that extend and formalize the ideas behind assert.

Feature	assert (C macro)	static_assert (C++11)	Contracts (C++26 proposal)
Evaluation time	Runtime	Compile time	Runtime (configurable levels)
Disabled in release?	Yes (NDEBUG)	No — always checked	Configurable per build profile
Supported conditions	Any runtime-evaluable expression	Constant expressions only	Preconditions, postconditions, assertions
Custom message?	No (only expression text)	Yes (string literal)	Yes (via attributes)
Part of language?	Preprocessor macro (C library)	Language keyword	Language feature (proposed)

Comparison of assertion mechanisms in C++

Beyond C++ language features, assertions integrate naturally with broader correctness methodologies. Design by Contract (originated by Bertrand Meyer in Eiffel) formalizes preconditions and postconditions as contractual obligations between caller and callee. Property-based testing frameworks like Google Test or Catch2 use assertion-like macros (ASSERT_EQ, REQUIRE) that provide richer failure reporting without terminating the test suite. Formal verification tools can use assertions as proof obligations, statically verifying that they can never fail. Mastering the humble assert macro builds the mindset required for all of these advanced approaches.

SECTION 9

Practice Problems

Question 1: CONCEPTUAL

Explain the difference between an assertion and an exception in C++. Under what circumstances would you choose one over the other? Provide a concrete scenario for each.

Show answer

An assertion checks for conditions that should never be false if the program is correctly written — it guards against programmer errors (bugs). An exception handles conditions that can legitimately occur at runtime despite correct code, such as a missing file or invalid network response. For example, use assert(index < array.size()) when you control the caller and believe the index is always valid. Use throw std::runtime_error("file not found") when opening a user-supplied filename, because the file's existence is outside the program's control. A key practical distinction is that assertions are disabled in release builds via NDEBUG, while exception handling remains active.

Question 2: BASIC CALCULATION

Consider the following function. Identify which assertions are appropriate and which are problematic. Explain your reasoning for each.

double safeDivide(double num, double den) {
  assert(den != 0.0);           // (A)
  double result = num / den;
  assert(result == num / den);  // (B)
  assert(++callCount > 0);      // (C)
  return result;
}

Show answer

Assertion (A) is appropriate if the function contract specifies that den must be non-zero and the caller is responsible for ensuring this — it documents a precondition. However, if the function is meant to handle user-supplied input, this should be an exception or error return instead. Assertion (B) is technically valid but redundant and wasteful — it merely re-evaluates the same expression, adding nothing in terms of invariant checking. Assertion (C) is dangerous because it contains a side effect: the increment operator ++callCount modifies state. In release builds with NDEBUG defined, this entire expression is removed, so callCount will never be incremented, silently changing the program's behavior.

Question 3: INTERMEDIATE

Write a C++ function int factorial(int n) that computes n! iteratively. Add assertions for: (1) a precondition that n is non-negative, (2) a loop invariant that the running product remains positive (no integer overflow), and (3) a postcondition that the result is at least 1. Show the complete function.

Show answer

A correct implementation would be:

#include <cassert>
int factorial(int n) {
  assert(n >= 0);  // precondition
  int result = 1;
  for (int i = 2; i <= n; ++i) {
    result *= i;
    assert(result > 0);  // loop invariant: no overflow
  }
  assert(result >= 1);  // postcondition
  return result;
}

The precondition catches negative inputs which have no factorial definition. The loop invariant catches integer overflow — for 32-bit int, factorial(13) overflows, so the assertion will fire for n ≥ 13, alerting the developer that a wider integer type is needed. The postcondition confirms the mathematical property that n! ≥ 1 for all n ≥ 0.

Question 4: APPLIED

You are implementing a circular buffer class with a fixed capacity. The class has members int* data_, size_t capacity_, size_t size_, size_t head_, and size_t tail_. Write a private method void checkInvariant() const that uses assertions to verify the representation invariant. Include at least four meaningful assertions.

Show answer

A robust checkInvariant method would be:

void checkInvariant() const {
  assert(data_ != nullptr);           // buffer must be allocated
  assert(capacity_ > 0);              // capacity must be positive
  assert(size_ <= capacity_);         // can't hold more than capacity
  assert(head_ < capacity_);          // head index in range
  assert(tail_ < capacity_);          // tail index in range
  assert((tail_ + capacity_ - head_) % capacity_ == size_ % capacity_); // structural consistency
}

The first assertion ensures the buffer is allocated. The second prevents a degenerate zero-capacity buffer. The third enforces that size never exceeds capacity. The fourth and fifth ensure head and tail are valid indices. The sixth checks the structural relationship between head, tail, and size — in a correct circular buffer, the distance from head to tail (modulo capacity) must equal the size (modulo capacity). This method should be called at the end of every constructor and every mutating public method.

Question 5: CRITICAL THINKING

A colleague argues that assertions should never be used because they are disabled in production, where bugs actually cause damage. They propose using exceptions for all invariant checks instead. Construct a well-reasoned argument either supporting or refuting this position. Consider performance, semantics, recoverability, and software engineering best practices.

Show answer

The colleague raises a valid concern, but their proposed solution conflates two distinct categories of errors. Assertions guard against conditions that indicate a bug in the code itself — a violated invariant means the program's logic is fundamentally broken, and attempting to recover from a fundamentally broken state is unreliable and often dangerous. Throwing an exception and continuing implies that the error is recoverable, which is semantically misleading for a corrupted internal state. Furthermore, replacing all assertions with exceptions would impose runtime overhead for checks that, by definition, should never trigger in correct code — an O(n) sortedness check before every binary search, for example, would negate the algorithm's O(log n) advantage. The strongest counterpoint to the colleague's position is that assertions serve a different purpose than production error handling: they accelerate debugging during development by catching bugs at their source. The correct approach is to use assertions for internal invariants (programmer errors), exceptions for external conditions (runtime failures), and optionally implement a custom assertion macro that remains active in production with a configurable severity level, combining the best of both approaches.

SUMMARY

Lesson Summary

Summary

The C++ assert macro from <cassert> provides a lightweight, zero-overhead mechanism for enforcing invariants during development. Assertions encode the programmer's assumptions as executable Boolean checks: preconditions at function entry, loop invariants inside iteration bodies, postconditions before return, and class representation invariants at the end of constructors and mutating methods. When the condition evaluates to false, the macro prints a diagnostic to stderr and calls abort(), implementing the fail-fast philosophy.

In release builds, defining NDEBUG removes all assertions at the preprocessor level, ensuring zero runtime cost. This dual-mode behavior means assertions should never contain expressions with side effects. Assertions are for programmer errors (bugs), while exceptions and error codes handle runtime failures (external conditions). Complementary tools include static_assert for compile-time checks and the upcoming C++ Contracts feature for first-class language-level assertion support.