Before the C++ compiler sees a single line of code, a different program runs over the source file and rewrites it. That program is the preprocessor, and the directives that drive it (#include, #define, #undef, and the conditional family) operate as pure text substitution, with no awareness of types, scopes, or even C++ syntax. This chapter covers what the preprocessor does, how #define builds object-like and function-like macros, the stringize (#) and token-paste (##) operators, the classic macro pitfalls, and why modern C++ replaces most macros with constexpr, inline, and enum class.

Running g++ shop.cpp -o shop looks like one step, but the toolchain is a small pipeline. The preprocessor runs first, takes the .cpp file plus everything it pulls in via #include, expands every macro, evaluates every conditional directive, and produces a single flat translation unit as plain text. That text is what the compiler sees. Only after the preprocessor finishes do the parser, type checker, and code generator get involved.

Each box is a real program on a typical Linux install: cpp does preprocessing, cc1plus is the C++ compiler proper, as turns assembly into object files, and ld links the pieces together. To stop after the first stage and see what the preprocessor handed downstream, pass -E to g++:

Running g++ -E shop.cpp prints the post-preprocessor text. The body of main becomes int cart[100]; because the preprocessor walked through the file and replaced every occurrence of the token MAX_CART_ITEMS with 100. The compiler never sees the name MAX_CART_ITEMS at all. This detail explains many of the surprises macros produce.

A few properties fall out of this design:

The simplest form of #define binds a name to a replacement token sequence. Anywhere the preprocessor sees the name (outside string literals and comments), it substitutes the replacement.

Read each #define as a rewrite rule. MAX_CART_ITEMS -> 100, DEFAULT_CURRENCY -> "USD", and so on. The replacement runs through the rest of the file (or until an #undef), in every context where the name appears as a standalone token.

A few common gotchas:

Because the preprocessor is text substitution, a macro has no type. MAX_CART_ITEMS isn't an int; it's the literal string 100 that the compiler will later parse as an integer literal. Taking its address fails:

The error talks about &100, not about MAX_CART_ITEMS. The macro is gone by the time the compiler complains. This is one of several reasons modern code prefers constexpr for named constants, covered later.

Macros can take parameters. The syntax looks like a function definition, but the semantics are still pure text substitution.

The call MAX(price1, price2) is rewritten to ((price1) > (price2) ? (price1) : (price2)) before the compiler sees anything. There's no function call at runtime, no stack frame, no argument copying. The preprocessor pastes the arguments into the body.

The parentheses look excessive. They're not. Every argument is wrapped in parens, and the whole body is wrapped in one more pair. Without those parens, two classic macro bugs (precedence and side-effect bugs) appear.

Function-like macros also accept variable arguments via ... and __VA_ARGS__, which makes printf-style logging macros possible:

The backslash at the end of the first line continues the macro definition onto the next physical line. The preprocessor stitches them together before substitution. __VA_ARGS__ expands to the comma-separated list of arguments that matched .... Adjacent string literals ("[order] " format "\n") are concatenated by the compiler, not the preprocessor.

Function-like macros look like functions, but they don't behave like functions, and the most common bug comes from forgetting that. A version of SQUARE that drops the inner parens:

What's wrong with this code?

Expected 25, because (2 + 3) * (2 + 3) == 25. The output is 11. The macro expands by pasting the argument text in place, so SQUARE(2 + 3) becomes 2 + 3 * 2 + 3. Operator precedence kicks in: 3 * 2 runs first, then the additions, giving 2 + 6 + 3 = 11.

Fix: Wrap every parameter use in parentheses, and wrap the entire body in one more pair:

Now SQUARE(2 + 3) expands to ((2 + 3) * (2 + 3)), which evaluates to 25 regardless of what surrounds the call site.

The outer parens matter too. 10 / SQUARE(2) with #define SQUARE(x) (x) * (x) expands to 10 / (2) * (2), which is 10, not 2.5. Wrapping the whole body in parens fixes that: ((2) * (2)) becomes a single grouped expression.

The rule is mechanical and unforgiving: every parameter in parens, every body in parens, no exceptions. It looks ugly. The alternative is bugs that survive review and only appear at runtime when someone passes an expression instead of a single token.

Even with perfect parens, function-like macros have a second hazard: they evaluate their arguments more than once.

What's wrong with this code?

Reading MAX as a function suggests next_id() runs once and the result is compared against 1005. It doesn't. The macro expands to:

next_id() runs once for the comparison, then runs again if the comparison picks the first branch, returning a different value the second time. The first call returns 1000 (so 1000 > 1005 is false, and the 1005 branch is taken), printing 1005. Worse, the side effect of incrementing id happens twice when the first branch is taken, and once when the second is. The behavior depends on which branch the ternary picks, which depends on the value the call returned.

Fix: Use a real function (or std::max):

std::max evaluates each argument exactly once before the comparison. Any function-like macro that uses an argument more than once in its body has this hazard, and it can't be fixed inside the macro: the argument text is what gets pasted, and pasting it twice means evaluating it twice.

Function-like macros look "free" because there's no call overhead, but multiple-evaluation can double or triple the work of a non-trivial argument. An inline function gives the same zero call overhead without the trap.

Macros live in a separate namespace (or rather, no namespace at all) from C++ names. They don't respect {} blocks, classes, namespaces, or templates. Once defined, a macro is active until an #undef or the end of the translation unit.

This doesn't compile. The preprocessor finds DISCOUNT inside namespace shop and substitutes 10, producing int 10 = 25;, which makes no sense as a declaration. The namespace doesn't protect anything; the preprocessor doesn't know namespaces exist.

The same problem appears with member names, parameter names, and even strings of source code that share a name with a macro. Windows headers famously define min and max as macros, which collides with std::min and std::max. The workaround is #define NOMINMAX before including the Windows headers, or wrapping calls in parens: (std::min)(a, b) so the preprocessor doesn't see min as a macro name.

Macros also have no type. They can't be overloaded, passed to a template, have their address taken, or put in a header behind a class:

The class member LIMIT is an int, lives inside Cart, and can be referenced as Cart::LIMIT. The macro is a free-floating text rule with none of those properties.

Inside a function-like macro body, prefixing a parameter with # turns its argument into a string literal. This is the stringize operator. The preprocessor takes the text of the argument, adds quotes, and escapes any embedded \ or " characters.

LABEL(cart_total) expands to "cart_total", with the quotes added by the preprocessor. LABEL(2 + 3) expands to "2 + 3", preserving whitespace as it appeared in the source. The argument is never evaluated as an expression: the macro sees its text, not its value.

A common use is an assertion-like macro that prints the failed condition:

If cartItems were 0, the macro would print Requirement failed: cartItems > 0 and exit. The #cond inside the body grabs the literal source text of the condition and turns it into a string, useful for error messages because the condition expression can't usually print itself.

The do { ... } while (0) wrapper is a classic macro idiom. It makes the macro behave like a single statement that requires a trailing semicolon, even when used inside an if/else without braces, without dangling-else surprises.

The token-paste operator ## joins two tokens into one during macro expansion. It's the tool for building identifier names from pieces.

price_##name pastes the literal text price_ onto whatever name expands to, producing a single identifier price_mouse or price_keyboard. The result has to be a valid token, so pasting something the lexer can't parse (e.g., 1 and +) won't produce a usable token.

A useful pattern combines # and ## to generate logging keys:

The #category and #name build the human-readable key "cart.size", while metric_##category##_##name builds the variable name metric_cart_size. The same call site produces both a string label and an identifier reference.

Token pasting is the only way to programmatically generate names in C++, but heavy use of ## is a sign that a template, a std::map<std::string, int>, or a code-generation step would fit better.

A macro stays defined from its #define to the end of the translation unit, unless an #undef removes it.

Redefining a macro to the same replacement is fine. Redefining it to a different replacement without an #undef first is technically an error, though most compilers downgrade it to a warning. #undef of a name that isn't currently defined is harmless and does nothing.

#undef undoes a macro from a third-party header that conflicts with your code. Include the offending header, immediately #undef the offending name, then continue. The min/max Windows macros are the canonical example.

For most cases where macros showed up in older C++ code, modern C++ has a better answer. Macros lose type information, ignore scope, and play tricks during preprocessing that the rest of the language doesn't get to see. The alternatives keep all of that, and they cost nothing at runtime.

The same MAX written three ways. The macro version is what appears in C code from twenty years ago. The inline version is what most C++ programmers wrote between 1998 and 2011. The constexpr template is the modern form.

The inline int max_i(int, int) is restricted to int arguments. The constexpr template version works for int, double, std::string, anything with operator>. Both versions evaluate each argument exactly once, both respect scope, both can be debugged, both produce the same machine code as the macro after the optimizer runs.

For named constants, the comparison is even more lopsided:

None of that works with #define MAX_CART_ITEMS_OLD 100. Taking the address of the macro doesn't compile, type information is lost the moment the preprocessor expands the name, and a debugger watching the program won't show MAX_CART_ITEMS_OLD as a symbol because there's no symbol to show.

For named sets of values, enum class replaces the worst pattern macros used to fill:

The enum class rejects raw integers, requires the OrderStatus:: prefix at use sites, and lets the compiler catch typos like OrderStatus::Sipped. The macro version compiles STATUS_SIPPED as an undefined identifier with no way to tell the typo wasn't intentional.

constexpr constants and inline functions don't add any runtime cost compared to macros. The compiler folds them away at the same point in the pipeline. The macro's only "advantage" is being invisible to the type system, which is the same as saying it's untrustworthy.

After all of the warnings, there are still places where macros are the right tool, because the alternatives can't express what's needed.

Outside of those, reach for constexpr first, inline second, enum class third, and template fourth. Macros come last, after ruling out everything else.