Abstract:

This presentation by Matt Godbolt at C++ on Sea explores techniques for designing C++ APIs using a "correct by construction" approach, aiming to prevent misuse and catch errors at compile time. Drawing on experience in demanding industries, Godbolt demonstrates how to leverage C++ features such as strong value types, enum class, static_assert, RAII (Resource Acquisition Is Initialization), [[nodiscard]] attributes, and r-value reference qualified methods (&&) to create APIs that guide the user towards correct usage and make errors difficult. The talk also highlights the importance of enabling compiler warnings and using static analysis tools. Examples are used from finance, GUI development, and shader compilation.

Designing C++ APIs for Correctness: Leveraging the Compiler

• 0:00:25 Correct by Construction Philosophy: The core goal is for code that compiles to be (probably) correct, and for obviously wrong code to fail compilation, catching errors as early as possible, preferably at compile time.
• 0:01:11 Motivation from Experience: The speaker's background in industries like gaming (where patches were costly) and finance (where mistakes are very expensive) emphasized the need for code that is hard to misuse. This is not a replacement for testing or good design, but a complementary approach.
• 0:02:25 Every Piece of Code is an API: Even internal code is an API used by colleagues (including one's future self), so designing it well is crucial for collaboration and maintainability.
• 0:03:18 Problem with Primitive Types: Using raw int or double for distinct concepts (like quantity and price) can lead to silent, expensive errors if arguments are accidentally swapped, which default compiler warnings often miss.
• 0:05:20 Solution: Strong Value Types:
  • using or typedef are just aliases and don't create new types or prevent swaps (0:06:05).
  • Define distinct classes like Price and Quantity (0:06:32). This forces the compiler to see them as incompatible types.
  • Use explicit constructors for single-argument constructors (e.g., explicit Quantity(int val);) to prevent unintended implicit conversions from primitive types (0:07:50).
  • 0:10:00 Enforcing Value Invariants: For types like Quantity which shouldn't be negative:
    • Simply using unsigned int internally is insufficient; it requires enabling warnings like -Wsign-conversion.
    • Use static_assert with type traits (like std::is_unsigned_v<T>) in templated constructors or C++20 concepts (std::unsigned_integral) to prevent construction from signed/negative types at compile time (0:11:40). This might necessitate using 100u literals.
    • For values coming from potentially untrusted sources, use factory functions (e.g., static Quantity Quantity::from(int val)) with runtime checks (e.g., val >= 0) or gsl::narrow for safe conversions (0:14:00).
  • 0:15:47 User-Defined Literals (UDLs): Can simplify creating strong types, especially in tests (e.g., 100_qty, 1000.0_dollars).
  • 0:17:53 consteval for UDLs (C++20): Marking a UDL implementation consteval forces its evaluation at compile time, turning errors like out-of-range values into compilation failures.
  • 0:16:33 Note: Never represent financial prices using floating-point types like double; use integer types representing the smallest unit (e.g., pennies).
• 0:18:34 Solution: Avoid Naked Booleans & Use enum class: Replace boolean flags with enum class (e.g., enum class OrderSide { Buy, Sell };) for clarity, type safety, and self-documentation.
• 0:23:16 Turn Comments into Code (static_assert): Replace comments stating invariants (e.g., "// Must be 13 bytes long") with static_assert(sizeof(Header) == 13, "..."); to enforce them at compile time.
• 0:26:20 enum class for Protocol/State Types: Use enum class MessageType : char { Add = 'A', ... }; for message types in binary protocols or state machine states, providing type safety and improving readability over raw characters or integers.
• 0:28:06 switch Statements without default: When switching on an enum class, omitting the default case (with appropriate warnings enabled, e.g., -Wswitch-enum) allows the compiler to issue an error if a new enum value is added and not handled in the switch, helping locate all necessary code updates.
• 0:31:53 Identifying "Comment Smells": Comments like "// Must hold lock," "// Don't forget to unlock," or "// Must be compiled" indicate weak points in the API that rely on human memory and are ripe for improvement using compiler-enforced techniques.
• 0:32:50 Solution: RAII for Resource Management:
  • A lock() method should return an RAII object (e.g., ScopedLock) that acquires the lock in its constructor and releases it in its destructor, automating the unlock process and handling exceptions.
  • 0:34:25 [[nodiscard]] Attribute: Apply this attribute to the RAII object or the method returning it to prevent the caller from accidentally ignoring the returned object, which would cause the resource to be released prematurely.
• 0:35:16 Solution: Enforcing Operations within a Specific State (e.g., Locked):
  • 0:35:42 Wrapper Object: Return an RAII wrapper (Tinkerable or LockedWidget) from the state-acquiring method (lock()). This wrapper holds the state (the lock) and is the only object through which dependent operations (tinker_with()) can be called.
  • 0:37:48 Pass-a-Lambda: Provide a method (e.g., widget.tinker([](WidgetState& state){ ... });) that acquires the necessary state internally (the lock), then executes a provided lambda, passing access to the internal state, ensuring the state is held only for the duration of the lambda.
• 0:40:51 Solution: Separating Concerns & Signaling Consumption: For multi-step processes like shader compilation, split functionality (e.g., ShaderCompiler vs. CompiledShaders).
• 0:43:20 R-value Reference Qualifiers (&&) on Methods: Applying && to a method (e.g., CompiledShaders compile() &&;) restricts it to being called only on an r-value (a temporary object or one explicitly std::move'd). This signals that the object is consumed by the operation.
  • 0:58:51 Q&A Clarification: Calling compile() on a local variable explicitly requires std::move(compiler).compile();. Returning the compiler object itself (return compiler.compile();) might allow implicit move depending on context.
  • 0:46:16 Static Analysis Tools: Tools like Clang Tidy are crucial as standard compilers may not warn about use-after-move.
• 0:48:13 RAII (Resource Acquisition Is Initialization) is CADRe (Constructor Acquires, Destructor Releases): RAII's applicability extends far beyond just memory or file handles.
  • 0:51:17 RAII for Event Subscriptions: A subscribe() method can return an RAII object (Subscription) that registers the listener in its constructor and unregisters in its destructor, automating the unsubscribe process.
  • 0:53:31 Other CADRe Uses: Tracking indentation depth, recursion depth, re-entrancy flags (using a boolean and an RAII setter/resetter), and scope-based timers.
• 0:55:56 Key Takeaways: Look for "comment smells" as indicators of weak API points; turn on all compiler warnings, treat them as errors, and fix them; use strong value types and RAII/CADRe extensively to make APIs easy to use and hard to misuse.