C++ Core Guidelines

Express ideas directly in code

Code that reflects intent is easier to verify, optimize, and maintain than code that obscures it behind raw loops or pointers.

Write in ISO Standard C++

Extensions and vendor-specific features create portability debt and undefined behavior exposure.

Express intent

Algorithm names (ranges::sort, transform) say what you want; raw loops say how — prefer what.

Ideally, a program should be statically type safe

Type safety catches entire classes of bugs at compile time; use std::variant over unions, gsl::span over raw arrays.

Prefer compile-time checking to run-time checking

static_assert, constexpr, and concepts catch errors early; runtime checks carry overhead and can be skipped.

Don't waste time or space

Zero-overhead is C++'s core promise — don't use abstractions that cost more than direct code.

Prefer immutable data to mutable data

const and constexpr eliminate entire categories of concurrency bugs and enable better optimization.

Use supporting tools as appropriate

Static analyzers (clang-tidy), sanitizers (ASan/UBSan), and fuzzers find bugs compilers miss.

Make interfaces explicit

Implicit dependencies (globals, thread-locals) make code untestable and order-dependent.

Avoid singletons

Singletons create hidden global state, order-of-initialization problems, and untestable code.

Make interfaces precisely and strongly typed

Avoid bool flags and integer overloads; prefer strong types or enums so misuse doesn't compile.

Never transfer ownership by a raw pointer (T*) or reference (T&)

Pass ownership via unique_ptr; pass non-owning views via raw pointer or reference — be explicit.

Do not pass an array as a single pointer

Use std::span — it carries the size with the pointer, eliminating buffer overruns.

Keep the number of function arguments low

More than 4 arguments suggests a missing abstraction; group related parameters into a struct.

Encapsulate rule violations

If you must use a raw pointer or unsynchronized access, isolate it in a well-documented, well-tested class.

Package meaningful operations as carefully named functions

Functions are the unit of reuse, testing, and documentation — prefer them over inline lambda soup.

If your function must not throw, declare it noexcept

noexcept allows better code generation and documents guarantees to callers.

Prefer simple and conventional ways of passing information

In: T const& or by value. Out/in-out: T&. Ownership transfer: unique_ptr<T>. Avoid output parameters.

For 'in' parameters, pass cheaply-copied types by value and others by reference to const

Pass int/double/bool by value; pass std::string, std::vector by const&.

For 'out' output values, prefer return values to output parameters

Return values are clearer, composable, and work with structured bindings and [[nodiscard]].

Return a T* to indicate a position (only)

Returning a raw pointer signals non-owning; use optional<T&> or span for optional elements.

Where there is a choice, prefer default arguments over overloading

Default arguments keep the interface in one place; overloading multiplies documentation burden.

Use class if the class has an invariant; use struct if the data members can vary independently

struct signals a plain data aggregate; class signals an abstraction with enforced invariants.

If you can avoid defining any default operations, do

The Rule of Zero: let the compiler generate copy/move/destructor when all members manage themselves.

All resources acquired by a class must be released by the class's destructor

RAII: every resource has an owner; the destructor is the automatic cleanup guarantee.

A base class destructor should be either public and virtual, or protected and non-virtual

Deleting a derived object through a base pointer without a virtual destructor is undefined behavior.

Prefer in-class initializers to member initializers in constructors for constant initializers

In-class initializers are declared once and apply to all constructors automatically.

Make copy assignment non-virtual, take the parameter by const&, and return by non-const&

This is the conventional signature; deviations confuse users and compilers.

Use =default if you have to be explicit about using the default semantics

=default generates correct, efficient code; writing the body manually is error-prone.

Manage resources automatically using resource handles and RAII

Every resource should have an owning object whose destructor releases it — no exceptions (literally).

A raw pointer (T*) is non-owning

If a pointer owns a resource, use unique_ptr. Raw pointers are for non-owning access only.

Prefer scoped objects; don't heap-allocate unnecessarily

Stack allocation is faster, safer, and doesn't require deallocation — use it by default.

Avoid malloc() and free()

malloc bypasses constructors; free bypasses destructors. Use new/delete — or better, smart pointers.

Avoid calling new and delete explicitly

make_unique and make_shared provide exception safety and eliminate the new/delete imbalance class of bugs.

Use unique_ptr or shared_ptr to represent ownership

unique_ptr for exclusive ownership; shared_ptr for shared. Do not invent your own smart pointer.

Prefer unique_ptr over shared_ptr unless you need to share ownership

unique_ptr is zero-overhead; shared_ptr has atomic reference count cost. Only pay for what you need.

Prefer the standard library to other libraries and 'handcrafted code'

STL algorithms are optimized, tested, and communicate intent clearly to any C++ reader.

Keep scopes small

Shorter scope → fewer variables in play → fewer aliasing bugs → easier reasoning.

Declare one name (only) per declaration

int* p, q; — q is not a pointer. Separate declarations eliminate this class of surprise.

Always initialize an object

Uninitialized variables are undefined behavior in C++; zero-initialize or declare at point of first use.

Declare an object const or constexpr unless you want to modify its value later

const variables are immutable, more optimizable, and document intent.

Avoid narrowing conversions

double→int silently loses data. Use explicit casts or gsl::narrow_cast which asserts the value fits.

Don't dereference an invalid pointer

Dereferencing nullptr or a dangling pointer is undefined behavior — use references or optional.

Assume that your code will run as part of a multi-threaded program

Global/static state, non-const shared data, and lock-free patterns all require explicit reasoning.

Avoid data races

A data race on any non-atomic variable is undefined behavior — not just 'sometimes wrong'.

Use RAII, never plain lock()/unlock()

std::lock_guard and std::unique_lock ensure the mutex is released even on exceptions.

Use std::lock() or std::scoped_lock to acquire multiple mutexes

Acquiring multiple mutexes one-by-one in different order across threads causes deadlock.

Pass small amounts of data between threads by value, larger amounts by (smart) pointer

Shared mutable state is the root of data races — prefer message passing or const shared_ptr.

Minimize context switching

Context switches and cache misses dominate concurrent performance — design to minimize lock contention.

Develop an error-handling strategy early in a design

Mixing exceptions and error codes in an interface makes it impossible to write correct callers.

Use RAII to prevent leaks

Stack unwinding during exception propagation calls destructors — RAII makes this automatic.

Use noexcept when exiting a function because of a throw is impossible or unacceptable

noexcept allows destructors and move operations to be used in more contexts safely.

Don't try to catch every exception in every function

Only catch exceptions you can handle; let others propagate to a handler that can.

Avoid error handling based on global state (e.g., errno)

Global state is not thread-safe and creates hidden dependencies between functions.