Cpp Rules

C++ Rules

These rules come from app/rules/cpp/ in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in C++. Apply them when writing or reviewing C++ code.

C++ Coding Style

Naming

• PascalCase: classes, structs, enums, type aliases, concepts.
• camelCase or snake_case: functions, methods, variables (be consistent per project).
• UPPER_SNAKE: macros, compile-time constants.
• Prefix member variables with m_ or suffix with _ (pick one convention).
• Namespace names: lowercase, short (namespace io, namespace util).

Modern C++ (17/20/23)

• Use auto for iterator types and complex template deductions.
• Use std::optional<T> instead of sentinel values or pointers for optional returns.
• Use std::variant over union types. Use std::visit for dispatch.
• Use std::string_view for non-owning string parameters.
• Use structured bindings: auto [key, value] = *map.begin();.
• Use constexpr for compile-time evaluation. Prefer over macros.

Memory Management

• Use RAII exclusively. Every resource acquisition is an initialization.
• Use std::unique_ptr for exclusive ownership (default choice).
• Use std::shared_ptr only when ownership is genuinely shared.
• Never use raw new/delete. Use std::make_unique / std::make_shared.
• Use std::span<T> (C++20) for non-owning views over contiguous data.

Functions

• Pass small types by value. Pass large types by const&.
• Use [[nodiscard]] on functions whose return value must not be ignored.
• Use noexcept on functions that do not throw (move constructors, destructors).
• Limit function parameters to 4. Use structs for configuration objects.
• Use trailing return types for complex template return deductions.

Includes and Dependencies

• Use #pragma once or include guards. Prefer #pragma once for simplicity.
• Order: corresponding header, C++ stdlib, third-party, project headers.
• Forward-declare in headers when possible to reduce compile times.
• Minimize header dependencies. Use the Pimpl idiom for ABI stability.

Avoid

• Raw pointers for ownership. Use smart pointers.
• C-style casts. Use static_cast, dynamic_cast, const_cast.
• Macros for constants or functions. Use constexpr and templates.
• using namespace std; in headers. Acceptable in .cpp files with caution.
• std::endl -- use '\n' (endl flushes the buffer unnecessarily).

Formatting

• Use clang-format with a committed .clang-format file.
• Use clang-tidy for static analysis and automated modernization.
• Max line length: 100-120 characters.
• Braces: use Allman or K&R consistently per project.

C++ Frameworks

CMake

• Use modern CMake (3.14+): target-based, not directory-based.
• Use target_link_libraries with PUBLIC/PRIVATE/INTERFACE visibility.
• Use FetchContent for dependency management. Avoid manual submodule vendoring.
• Set CMAKE_CXX_STANDARD 20 (or 23) at the project level.
• Use target_compile_options for per-target flags, not global add_compile_options.
• Export targets with install(TARGETS ... EXPORT ...) for library consumers.

Boost

• Use Boost.Asio for async networking and I/O.
• Use boost::beast for HTTP/WebSocket built on Asio.
• Use boost::json or nlohmann/json for JSON parsing.
• Prefer C++ stdlib equivalents when available (e.g., std::optional over boost::optional).
• Link only the Boost libraries you actually use. Many are header-only.

Qt

• Use signals and slots for event-driven communication.
• Use QObject parent-child ownership for automatic memory management.
• Use QML for declarative UI. Keep business logic in C++ backend.
• Use QThread with worker objects (moveToThread), not subclassing QThread.
• Use smart pointers for non-QObject resources. QObject children are auto-deleted.

gRPC

• Define services in .proto files. Generate C++ stubs with protoc.
• Use async server with CompletionQueue for high-throughput services.
• Use grpc::ClientContext for per-call deadlines and metadata.
• Use interceptors for logging, auth, and metrics.
• Set deadlines on every RPC call to prevent hanging.

Networking (Asio)

• Use io_context as the event loop. Run from one or more threads.
• Use co_await (C++20 coroutines) with Asio for clean async code.
• Use strand for serializing access to shared state across handlers.
• Use steady_timer for timeouts and periodic tasks.
• Handle errors via error_code parameter, not exceptions, in async callbacks.

Database

• Use libpq (PostgreSQL) or SOCI for database access.
• Use prepared statements exclusively. Never concatenate SQL strings.
• Use connection pooling for multi-threaded server applications.
• Use SQLite via sqlite3 C API with RAII wrappers for embedded use cases.

Package Management

• Use vcpkg or Conan 2 for dependency management.
• Pin dependency versions in vcpkg.json or conanfile.py.
• Use CI caching for build artifacts and dependency downloads.
• Prefer pre-built binary packages for CI speed.

C++ Patterns

Error Handling

• Use exceptions for truly exceptional conditions. Use return types for expected failures.
• Use std::expected<T, E> (C++23) or Result<T, E> pattern for recoverable errors.
• Use std::error_code / std::error_category for system-level errors.
• Use noexcept on functions that must not throw (destructors, move operations).
• Catch by const&. Never catch by value (slicing) or pointer.

RAII Patterns

• Wrap every resource (memory, file, lock, socket) in an RAII type.
• Use std::lock_guard or std::scoped_lock for mutex management.
• Use std::unique_lock when deferred locking or condition variables are needed.
• Use std::fstream (auto-closes) instead of fopen/fclose.
• Write custom RAII wrappers for C library resources (file descriptors, handles).

Smart Pointer Patterns

• unique_ptr: default ownership model. Transfer with std::move.
• shared_ptr: use only for genuinely shared ownership graphs.
• weak_ptr: break cycles in shared_ptr graphs. Use lock() to access.
• Factory functions should return unique_ptr. Let callers upgrade to shared_ptr.
• Never pass smart pointers by reference. Pass T& or T* to non-owning consumers.

Concurrency

• Use std::thread with std::jthread (C++20) for auto-joining threads.
• Use std::mutex + std::scoped_lock for shared data protection.
• Use std::atomic<T> for lock-free single-variable synchronization.
• Use std::condition_variable for producer-consumer patterns.
• Use std::async / std::future for simple parallel computation.
• Use std::counting_semaphore (C++20) for resource pool limiting.

Template Patterns

• Use CRTP for compile-time polymorphism (static dispatch).
• Use concepts (C++20) to constrain template parameters with clear error messages.
• Use if constexpr for compile-time branching in templates.
• Use variadic templates and fold expressions for parameter packs.
• Prefer constexpr functions over template metaprogramming when possible.

Design Patterns

• Use std::variant + std::visit for type-safe visitor pattern.
• Use std::function for type-erased callbacks and strategy pattern.
• Use Pimpl idiom (unique_ptr<Impl>) for ABI stability and compilation firewall.
• Use Builder pattern with method chaining for complex object construction.
• Use std::move semantics in move constructors for efficient resource transfer.

Anti-Patterns

• Raw new/delete: use smart pointers and containers.
• Returning raw pointers from factory functions: return unique_ptr.
• const_cast to remove constness: redesign the interface.
• Deep inheritance hierarchies: prefer composition and templates.
• Premature optimization over readability: profile first, optimize second.