Abstract:

This talk by Tina provides a comprehensive guide to writing expressive and self-documenting C++ code, emphasizing the principle that "the code is documentation enough." Grounded in the C++ Core Guidelines, the presentation argues that clear code is safer, more maintainable, and easier to understand than code that relies on comments to explain what it does.

The speaker systematically covers best practices across several key areas. These include crafting descriptive and consistent names for variables and functions; leveraging strong types and unit libraries to enhance type safety and clarity; and structuring code into small, single-purpose functions with limited parameters. The talk also highlights the role of unit tests as a form of executable documentation that clarifies a function's behavior and edge cases. Modern C++ language features like const, concepts, and upcoming contracts are presented as powerful tools for expressing intent directly in the code. Finally, the presentation defines the appropriate use of comments: to explain the "why"—such as workarounds, complex algorithms, or strategic decisions—rather than the "what," which the code itself should convey.

Mastering Expressive Code: A Guide to Self-Documenting C++

• 0:00:53 — The Goal: Expressive Code: The talk's central thesis is that code should be written to be as clear as possible, following the C++ Core Guideline "Express ideas directly in code." This makes the code easier to maintain and reduces the need for comments.
• 0:03:51 — Descriptive Variable Naming: Good variable names are crucial for readability. Instead of generic names, use descriptive ones that explain the purpose of the variable (e.g., sum_of_weights instead of s2). Intermediate variables can also be used to name the stages of a complex algorithm.
• 0:09:46 — Clear Function Naming: A function's name should describe what it does. Use verb-object pairs (e.g., get_balance, update_balance) and prefixes like is, has, or can for functions returning a boolean. A function should have one clear purpose.
• 0:13:45 — The Power of Strong Types: Using primitive types like double for distinct concepts (e.g., distance and time) can lead to ambiguity and errors. Strong types prevent this.
  • 0:17:18: While type aliases (typedef/using) improve readability, they are not type-safe and don't prevent incorrect parameter swapping.
  • 0:17:46: Creating custom structs provides true type safety, making it impossible to mix up incompatible units at compile time.
  • 0:19:54: For common cases like physical units, use a dedicated library (e.g., MP-Units) to gain type safety without having to write extensive boilerplate code.
• 0:23:08 — Effective Code Organization: Avoid "spaghetti code" by breaking large functions into smaller, single-purpose functions. This improves readability, testability, and reusability.
  • 0:25:39: Maintain a single layer of abstraction within each function. Don't mix high-level calls with low-level implementation details.
  • 0:26:31: Limit the number of function parameters (ideally 3-4 max). Group related parameters into a struct.
  • 0:27:46: Avoid deeply nested code by using early returns to handle preconditions and error cases at the beginning of a function.
• 0:29:49 — Unit Tests as Documentation: Well-written unit tests serve as documentation, demonstrating how to use a function and clarifying its behavior on edge cases (e.g., handling empty input). Test names should be descriptive, explaining what is being tested.
• 0:33:51 — Leveraging Language Features: Use modern C++ features to make intent clear.
  • 0:35:03: Use const everywhere possible to signal that a value or object state will not change. This reduces cognitive load for the reader.
  • 0:36:27: Use concepts to enforce template parameter requirements at compile time, making function interfaces much clearer than older SFINAE techniques.
  • 0:37:49: Upcoming C++26 contracts will allow developers to formally specify pre- and post-conditions directly in the function's interface.
• 0:41:04 — When and How to Write Comments: A comment should explain the "why," not the "what."
  • 0:41:22: Bad comments are redundant, outdated, or just TODOs that should be in an issue tracker.
  • 0:42:43: Good comments explain the reasoning behind a choice (e.g., using stable_sort), document a workaround for a bug, clarify complex mathematics, or justify disabling a static analysis warning.
• 0:45:03 — Enforcing Readability: While tools like Clang-Tidy and formatters can enforce rules, true readability is a human concern. Use code reviews and pair programming to ensure the code is understandable to others.