Cpp coding

C++ Best Practices

Comprehensive guide for writing high-quality, idiomatic modern C++. Contains 176 rules across 15 categories, prioritized by impact. Project constraints override generic defaults: preserve the declared CMAKE_CXX_STANDARD/-std= flag, compiler support matrix, and existing memory-management conventions unless the user explicitly requests a modernization pass.

This skill is for idiomatic modern C++ — RAII, smart pointers, templates, the STL, exceptions/std::expected. For plain C code (manual memory management, no classes/templates/exceptions, C ABI), use the sibling c-coding skill instead. Do not apply C++-only idioms (RAII, unique_ptr, templates, exceptions) to a .c file, and do not apply C-style manual memory management to idiomatic C++.

When to Apply

Reference these guidelines when:

• Writing new C++ classes, functions, or headers
• Choosing between unique_ptr, shared_ptr, raw pointers, and references
• Implementing error handling (exceptions, std::expected, error codes)
• Designing public APIs for a library or shared object
• Reviewing code for ownership, lifetime, or memory-safety issues
• Writing template or generic code, or migrating SFINAE to concepts
• Writing or reviewing concurrent code (threads, atomics, coroutines)
• Optimizing hot paths or reducing allocations
• Setting up CMakeLists.txt, .clang-tidy, or CI sanitizer builds

Modern C++ (C++17 / C++20 / C++23)

Preserve the project's declared standard (CMAKE_CXX_STANDARD, -std=c++XX) and compiler baseline unless migration is explicitly in scope. For new projects, prefer at minimum C++17 for structured bindings and if constexpr, and C++20 where the toolchain (GCC 10+, Clang 14+, MSVC 19.29+) reliably supports it.

C++17 — genuinely current baseline:

• Structured bindings (auto [it, ok] = map.insert(...)) instead of .first/.second
• if constexpr for compile-time branching without SFINAE tricks
• std::optional<T>, std::variant<T...>, std::any for absence/sum-types/type-erasure
• std::string_view for non-owning string parameters
• Class template argument deduction (CTAD) — std::vector v{1, 2, 3}; needs no <int>
• std::filesystem for portable path/file operations
• [[nodiscard]], [[maybe_unused]], [[fallthrough]] attributes

C++20 — adopt where the toolchain supports it:

• Concepts (std::integral, std::invocable, user-defined requires clauses) instead of enable_if/SFINAE
• Ranges (std::ranges::sort, views, pipe composition) instead of iterator-pair algorithms
• Coroutines (co_await/co_yield/co_return) for structured async code
• std::span<T> for bounds-aware, non-owning views over contiguous data
• std::jthread (auto-joining, cooperatively cancellable thread)
• Modules (import/export module) — adopt only after confirming build-system maturity (CMake 3.28+, compiler support); header/#include remains the safe default otherwise
• Three-way comparison (operator<=>) to replace hand-written relational operator sets
• Designated initializers, std::atomic_ref, std::format (or {fmt} as the pre-standard equivalent)

C++23 — use only when the project's toolchain is confirmed current enough:

• std::expected<T, E> for explicit, allocation-free error returns as an alternative to exceptions
• Deducing this (explicit object parameters) to de-duplicate const/non-const and ref-qualified overloads
• std::mdspan for multi-dimensional array views
• if consteval for compile-time-vs-runtime branching
• std::ranges::to for materializing ranges into containers

For the authoritative, evolving detail, consult the C++ Core Guidelines and cppreference.com's per-standard feature pages. Everything below applies across C++17/20/23; prefer the newer forms above where the project's standard version allows.

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	RAII & Resource Management	CRITICAL	raii-	12
2	Smart Pointers & Ownership	CRITICAL	own-	13
3	Memory Safety	CRITICAL	mem-	14
4	Error Handling	CRITICAL	err-	13
5	Templates & Generic Programming	HIGH	tmpl-	12
6	API Design	HIGH	api-	14
7	Concurrency	HIGH	conc-	14
8	Naming Conventions	MEDIUM	name-	10
9	Type Safety	MEDIUM	type-	11
10	Testing	MEDIUM	test-	10
11	Documentation	MEDIUM	doc-	8
12	Performance Patterns	MEDIUM	perf-	12
13	Project Structure	LOW	proj-	9
14	Linting & Static Analysis	LOW	lint-	9
15	Anti-patterns	REFERENCE	anti-	15

---

Quick Reference

1. RAII & Resource Management (CRITICAL)

• raii-scope-bound-resources - Bind every resource to a scope-owning object
• raii-rule-of-zero - Prefer Rule of Zero; let members manage their own resources
• raii-rule-of-five - Implement all five special members together, or none
• raii-unique-ptr-default - Default to unique_ptr for sole ownership
• raii-custom-deleter - Use custom deleters for non-memory resources
• raii-lock-guard - Use lock_guard/scoped_lock, never manual lock/unlock
• raii-scope-exit - Use RAII scope guards instead of goto-cleanup
• raii-no-manual-new-delete - Never pair manual new/delete; wrap in an owner
• raii-exception-safety-dtor - Destructors must not throw; mark noexcept
• raii-avoid-two-phase-init - Avoid two-phase init; fully construct in the constructor
• raii-raii-for-transactions - Use RAII for transactional commit/rollback
• raii-file-handle-wrap - Wrap OS/file handles in RAII types

2. Smart Pointers & Ownership (CRITICAL)

• own-unique-ptr-sole - unique_ptr for sole, transferable ownership
• own-shared-ptr-shared - shared_ptr only for genuine shared ownership
• own-weak-ptr-break-cycles - weak_ptr to break shared_ptr cycles
• own-make-unique-shared - Use make_unique/make_shared over raw new
• own-raw-pointer-non-owning - Raw pointer/reference means non-owning
• own-span-view - Use std::span/string_view for non-owning views
• own-pass-by-value-sink - Take ownership by value (unique_ptr) when sinking
• own-observer-ptr-reference - Prefer reference over pointer when null is invalid
• own-shared-ptr-not-default - Don't default to shared_ptr "just in case"
• own-enable-shared-from-this - Use enable_shared_from_this correctly
• own-const-correctness-ownership - Distinguish ownership from access via const
• own-move-transfer - Use std::move to transfer ownership explicitly
• own-avoid-get-raw-escape - Don't let .get() pointers outlive their owner

3. Memory Safety (CRITICAL)

• mem-span-bounds - Use std::span instead of pointer+length pairs
• mem-string-view-borrow - Use std::string_view for read-only string params
• mem-array-over-c-array - Use std::array instead of raw C arrays
• mem-vector-over-manual - Use std::vector instead of manual dynamic arrays
• mem-at-vs-brackets - Use .at() at boundaries, operator[] in verified hot paths
• mem-no-dangling-reference - Never return references/pointers to locals
• mem-iterator-invalidation - Know which operations invalidate iterators
• mem-use-after-move - Don't use an object after std::move except to reassign
• mem-avoid-c-style-arrays-decay - Avoid array-to-pointer decay in interfaces
• mem-sanitizer-required - Run ASan/UBSan in test builds, not just release
• mem-no-manual-index-arithmetic - Avoid manual pointer/index arithmetic
• mem-null-check-before-deref - Check pointer validity before dereference
• mem-lifetime-of-callback-captures - Don't let lambda captures dangle
• mem-string-lifetime-c-str - Don't retain c_str()/data() past source lifetime

4. Error Handling (CRITICAL)

• err-exceptions-vs-expected - Choose exceptions vs std::expected/error codes
• err-raii-exception-safety - Rely on RAII for exception-safe cleanup
• err-strong-exception-guarantee - Provide at least the basic guarantee
• err-noexcept-correctness - Mark move operations noexcept
• err-no-exceptions-across-abi - Don't let exceptions cross extern "C"
• err-expected-for-recoverable - Use std::expected<T,E> for recoverable failures
• err-optional-for-absence - Use std::optional<T> for absence, not errors
• err-catch-by-const-ref - Catch exceptions by const&, not by value
• err-no-catch-all-swallow - Don't swallow exceptions with empty catch(...)
• err-custom-exception-hierarchy - Derive custom exceptions from std::exception
• err-nodiscard-fallible - Mark fallible functions [[nodiscard]]
• err-error-context-preserve - Preserve original cause when wrapping errors
• err-assert-vs-exception - assert() for programmer errors, exceptions for runtime errors

5. Templates & Generic Programming (HIGH)

• tmpl-concepts-over-sfinae - Use C++20 concepts instead of SFINAE
• tmpl-if-constexpr-branch - Use if constexpr for compile-time branching
• tmpl-requires-clause - Use requires clauses to constrain templates precisely
• tmpl-avoid-bloat - Minimize template instantiation bloat
• tmpl-crtp-static-polymorphism - Use CRTP for static polymorphism
• tmpl-variadic-parameter-pack - Use variadic templates and fold expressions
• tmpl-auto-template-param - Use abbreviated function templates for simple generics
• tmpl-concept-standard-library - Prefer standard concepts over ad hoc traits
• tmpl-explicit-instantiation - Use explicit instantiation to control compile time
• tmpl-type-traits-standard - Use <type_traits> instead of hand-rolled checks
• tmpl-template-template-param - Use template template parameters judiciously
• tmpl-constexpr-function - Prefer constexpr functions over metaprogramming

6. API Design (HIGH)

• api-rule-of-zero-value-types - Value types: rule of zero
• api-const-correctness - Mark methods/parameters const wherever possible
• api-pass-by-value-sink-ref-view - Decision table for parameter passing
• api-nodiscard-return - Annotate [[nodiscard]] on must-check returns
• api-pimpl-abi-stability - Use PIMPL for ABI-stable shared libraries
• api-avoid-stl-across-abi - Don't expose STL containers across unstable ABI
• api-explicit-constructors - Mark single-argument constructors explicit
• api-return-value-not-out-param - Return values instead of out-parameters
• api-interface-segregation - Keep interfaces small and focused
• api-default-member-init - Use default member initializers
• api-strong-types-over-bool - Use enum class instead of multiple bools
• api-consistent-overload-set - Keep overload sets consistent and unambiguous
• api-header-only-inline - Mark header-only free functions inline
• api-deprecated-attribute - Use [[deprecated]] before removing API

7. Concurrency (HIGH)

• conc-jthread-over-thread - Prefer std::jthread over std::thread
• conc-lock-guard-raii - Always guard mutexes with RAII lock types
• conc-avoid-data-races - Guard every piece of shared mutable state
• conc-atomic-for-simple-state - Use std::atomic for simple counters/flags
• conc-lock-ordering-deadlock - Establish lock ordering or use scoped_lock
• conc-condition-variable-predicate - Always guard wait with a predicate
• conc-async-future-tasks - Use std::async/std::future for simple parallelism
• conc-coroutines-async-io - Use C++20 coroutines for structured async I/O
• conc-thread-pool-over-raw-threads - Use a thread pool, not raw threads per task
• conc-shared-mutex-readers - Use std::shared_mutex when reads dominate
• conc-avoid-detach - Avoid std::thread::detach()
• conc-immutable-sharing - Prefer sharing immutable data over synchronizing mutable data
• conc-thread-local-storage - Use thread_local for per-thread state
• conc-memory-order-relaxed-care - Default to seq_cst; justify weaker orders

8. Naming Conventions (MEDIUM)

• name-types-pascal - PascalCase for types, classes, enums, concepts
• name-functions-lower-snake - lower_snake_case for functions and variables
• name-member-trailing-underscore - Trailing underscore for private members
• name-constants-kcamel-or-caps - One consistent constant convention project-wide
• name-macros-all-caps - ALL_CAPS only for macros
• name-namespace-lower-snake - Short lower_snake_case namespaces
• name-template-param-single-letter - Single-letter or PascalCase template params
• name-boolean-is-has - Prefix booleans with is_/has_/can_
• name-file-name-match-class - Match file name to primary type name
• name-avoid-hungarian - Avoid Hungarian notation in modern C++

9. Type Safety (MEDIUM)

• type-enum-class-over-enum - Use enum class instead of unscoped enum
• type-strong-typedef-ids - Wrap raw ids/handles in strong types
• type-optional-nullable - Use std::optional<T> instead of sentinel values
• type-variant-over-union - Use std::variant instead of raw unions
• type-avoid-c-style-cast - Use named casts, never C-style casts
• type-dynamic-cast-polymorphic - Use dynamic_cast/visitor over manual type tags
• type-narrowing-conversion-explicit - Make narrowing conversions explicit
• type-auto-when-clear - Use auto when the type is obvious or noisy
• type-structured-bindings - Use structured bindings to unpack aggregates
• type-any-for-heterogeneous - Use std::any sparingly, only for real type erasure
• type-strongly-typed-units - Use strongly-typed units instead of raw numerics

10. Testing (MEDIUM)

• test-gtest-fixtures - Use GoogleTest fixtures (TEST_F) for shared setup
• test-catch2-sections - Use Catch2 SECTION for given/when/then tests
• test-gmock-interfaces - Design mockable interfaces for gMock
• test-arrange-act-assert - Structure tests as arrange/act/assert
• test-sanitizer-ci - Run sanitizer builds as part of the test suite
• test-fuzz-entrypoints - Provide libFuzzer entry points for parsers
• test-death-test-invariants - Use death tests to verify invariant enforcement
• test-parameterized-tests - Use parameterized tests instead of copy-pasted cases
• test-no-shared-mutable-fixture - Avoid shared mutable state between tests
• test-mock-time - Inject a Clock abstraction for time-dependent code

11. Documentation (MEDIUM)

• doc-doxygen-public-api - Document all public API with Doxygen comments
• doc-brief-detailed-tags - Use \brief/\param/\return/\throws consistently
• doc-ownership-contract - Document ownership/lifetime for pointer parameters
• doc-thread-safety-contract - Document thread-safety guarantees
• doc-header-comment-invariants - Document class invariants near the declaration
• doc-example-usage - Provide a minimal usage example for non-trivial APIs
• doc-deprecated-migration - Document migration path for [[deprecated]] API
• doc-generated-docs-ci - Build Doxygen docs in CI to catch broken references

12. Performance Patterns (MEDIUM)

• perf-move-semantics - Use std::move to avoid unnecessary copies
• perf-emplace-over-push - Use emplace_back over push_back(T(...))
• perf-reserve-known-size - Call reserve() when final size is known
• perf-pass-by-const-ref-large - Pass large objects by const&
• perf-avoid-virtual-hot-path - Avoid virtual dispatch in hot inner loops
• perf-return-value-optimization - Rely on RVO/NRVO; return by value
• perf-avoid-shared-ptr-atomic-overhead - Avoid shared_ptr atomics in hot paths
• perf-cache-friendly-soa - Prefer structure-of-arrays for cache-friendly loops
• perf-avoid-unneeded-allocation - Avoid unnecessary heap allocation in loops
• perf-string-concatenation - Avoid repeated string concatenation
• perf-algorithm-over-handwritten-loop - Prefer <algorithm>/<ranges> over hand-written loops
• perf-profile-before-optimize - Profile before micro-optimizing

13. Project Structure (LOW)

• proj-header-source-split - Split declarations from definitions
• proj-include-guards-pragma-once - Use #pragma once in every header
• proj-avoid-circular-includes - Avoid circular includes via forward declarations
• proj-modules-adoption - Consider C++20 modules where toolchain support allows
• proj-minimal-includes - Include only what you use; forward-declare
• proj-namespace-per-library - Wrap library code in a project namespace
• proj-cmake-target-based - Use modern target-based CMake
• proj-separate-public-private-headers - Separate public and internal headers
• proj-precompiled-headers-large-builds - Use PCH/unity builds only after profiling

14. Linting & Static Analysis (LOW)

• lint-clang-tidy-baseline - Run clang-tidy with a curated check baseline
• lint-compiler-warnings-as-errors - Compile with -Wall -Wextra -Wpedantic -Werror
• lint-address-sanitizer - Build and test regularly with AddressSanitizer
• lint-undefined-behavior-sanitizer - Build and test with UndefinedBehaviorSanitizer
• lint-thread-sanitizer - Build and test concurrent code with ThreadSanitizer
• lint-cppcheck-static-analysis - Run cppcheck as a second opinion
• lint-clang-format-consistent - Enforce a single .clang-format style
• lint-warning-free-baseline - Treat new warnings as build failures
• lint-include-what-you-use-tool - Run include-what-you-use to keep includes minimal

15. Anti-patterns (REFERENCE)

• anti-raw-new-delete - Don't use raw new/delete for ownership
• anti-c-style-cast - Don't use C-style casts
• anti-using-namespace-std-header - Don't put using namespace std; in headers
• anti-output-parameters - Don't use output parameters when you can return a value
• anti-god-class - Don't build God classes with too many responsibilities
• anti-manual-memory-raii-available - Don't hand-manage memory when RAII suffices
• anti-macro-for-constants - Don't use #define for constants
• anti-macro-for-functions - Don't use function-like macros over templates/inline functions
• anti-naked-new-in-constructor - Don't leak resources when a constructor throws
• anti-shared-ptr-everywhere - Don't reach for shared_ptr as the default
• anti-catch-all-swallow - Don't write empty catch(...) blocks
• anti-void-star-type-erasure - Don't use void* when templates/variant/any exist
• anti-non-virtual-destructor-base - Don't give a polymorphic base a public non-virtual destructor
• anti-slicing-by-value - Don't pass/store polymorphic types by value
• anti-global-mutable-state - Don't rely on mutable global/static state

---

Recommended Tooling & Config

CMakeLists.txt warnings and sanitizers

add_library(myproject_warnings INTERFACE)
target_compile_options(myproject_warnings INTERFACE
  $<$<CXX_COMPILER_ID:GNU,Clang>:-Wall -Wextra -Wpedantic -Wshadow
    -Wconversion -Wsign-conversion -Wnon-virtual-dtor -Wold-style-cast
    -Woverloaded-virtual -Wnull-dereference -Wdouble-promotion
    -Werror>
  $<$<CXX_COMPILER_ID:MSVC>:/W4 /permissive- /WX>
)

option(ENABLE_SANITIZERS "Build with ASan+UBSan" OFF)
if(ENABLE_SANITIZERS)
  add_compile_options(-fsanitize=address,undefined -fno-omit-frame-pointer)
  add_link_options(-fsanitize=address,undefined)
endif()

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

target_link_libraries(my_target PRIVATE myproject_warnings)

.clang-tidy

Checks: >
  -*,
  bugprone-*,
  clang-analyzer-*,
  cppcoreguidelines-*,
  -cppcoreguidelines-avoid-magic-numbers,
  modernize-*,
  -modernize-use-trailing-return-type,
  performance-*,
  portability-*,
  readability-*,
  -readability-magic-numbers,
  -readability-identifier-length

WarningsAsErrors: 'bugprone-*,clang-analyzer-*,cppcoreguidelines-slicing'
HeaderFilterRegex: '^(include|src)/'
FormatStyle: file

---

How to Use

This skill provides rule identifiers for quick reference. When generating or reviewing C++ code:

1. Check relevant category based on task type
2. Apply rules with matching prefix
3. Prioritize CRITICAL > HIGH > MEDIUM > LOW
4. Read rule files in rules/ for detailed examples

Rule Application by Task

Task	Primary Categories
New class/struct	raii-, own-, api-
New free function	err-, name-, type-
Ownership/lifetime review	own-, mem-, raii-
Error handling	err-, api-
Generic/template code	tmpl-, type-
Concurrent code	conc-, own-, mem-
Performance tuning	perf-, mem-, conc-
Code review	anti-, lint-

---

Related Skills

• design-patterns - choosing and implementing GoF and idiomatic design patterns (also covers C++: RAII-based patterns, CRTP, PIMPL).
• security-review - security-audit checklists (memory safety, integer overflow, injection, concurrency hazards) for reviewing/auditing C++.
• c-coding - sibling skill for plain C (manual memory management, no classes/templates/exceptions, C ABI). Use cpp-coding for idiomatic modern C++ with RAII, smart pointers, templates, and the STL; use c-coding when the codebase is C or a C-compatible subset.

Sources

This skill synthesizes best practices from:

• C++ Core Guidelines (Stroustrup/Sutter)
• Effective Modern C++ by Scott Meyers
• cppreference.com per-standard feature documentation
• CERT C++ Coding Standard
• Production codebases: LLVM, Chromium, Abseil, Folly
• clang-tidy / cppcoreguidelines-* and modernize-* check documentation
• Community conventions (2024-2026)