From 4a2e29bc99c98490e1c5699d63572961776d2c78 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Wed, 12 Nov 2025 22:08:56 +0000 Subject: [PATCH] Change all explicitly created anchors to lowercase GitHub Flavored Markdown requires these anchors to be all-lowercase for markdown-style links within the document to work. Also change one anchor that uses '*' which isn't valid in HTML or Markdown. And rename duplicate anchor res-macros to res-macros3. --- CppCoreGuidelines.md | 3268 +++++++++++++++++------------------ scripts/hunspell/isocpp.dic | 46 +- 2 files changed, 1662 insertions(+), 1652 deletions(-) diff --git a/CppCoreGuidelines.md b/CppCoreGuidelines.md index 5ea72070c..14cb80a66 100644 --- a/CppCoreGuidelines.md +++ b/CppCoreGuidelines.md @@ -15,159 +15,159 @@ We make this project available to "friendly users" to use, copy, modify, and der Comments and suggestions for improvements are most welcome. We plan to modify and extend this document as our understanding improves and the language and the set of available libraries improve. -When commenting, please note [the introduction](#S-introduction) that outlines our aims and general approach. -The list of contributors is [here](#SS-ack). +When commenting, please note [the introduction](#s-introduction) that outlines our aims and general approach. +The list of contributors is [here](#ss-ack). Problems: * The sets of rules have not been completely checked for completeness, consistency, or enforceability. * Triple question marks (???) mark known missing information. * Update reference sections; many pre-C++11 sources are too old. -* For a more-or-less up-to-date to-do list see: [To-do: Unclassified proto-rules](#S-unclassified). - -You can [read an explanation of the scope and structure of this Guide](#S-abstract) or just jump straight in: - -* [In: Introduction](#S-introduction) -* [P: Philosophy](#S-philosophy) -* [I: Interfaces](#S-interfaces) -* [F: Functions](#S-functions) -* [C: Classes and class hierarchies](#S-class) -* [Enum: Enumerations](#S-enum) -* [R: Resource management](#S-resource) -* [ES: Expressions and statements](#S-expr) -* [Per: Performance](#S-performance) -* [CP: Concurrency and parallelism](#S-concurrency) -* [E: Error handling](#S-errors) -* [Con: Constants and immutability](#S-const) -* [T: Templates and generic programming](#S-templates) -* [CPL: C-style programming](#S-cpl) -* [SF: Source files](#S-source) +* For a more-or-less up-to-date to-do list see: [To-do: Unclassified proto-rules](#s-unclassified). + +You can [read an explanation of the scope and structure of this Guide](#s-abstract) or just jump straight in: + +* [In: Introduction](#s-introduction) +* [P: Philosophy](#s-philosophy) +* [I: Interfaces](#s-interfaces) +* [F: Functions](#s-functions) +* [C: Classes and class hierarchies](#s-class) +* [Enum: Enumerations](#s-enum) +* [R: Resource management](#s-resource) +* [ES: Expressions and statements](#s-expr) +* [Per: Performance](#s-performance) +* [CP: Concurrency and parallelism](#s-concurrency) +* [E: Error handling](#s-errors) +* [Con: Constants and immutability](#s-const) +* [T: Templates and generic programming](#s-templates) +* [CPL: C-style programming](#s-cpl) +* [SF: Source files](#s-source) * [SL: The Standard Library](#sl-the-standard-library) Supporting sections: -* [A: Architectural ideas](#S-A) -* [NR: Non-Rules and myths](#S-not) -* [RF: References](#S-references) -* [Pro: Profiles](#S-profile) +* [A: Architectural ideas](#s-a) +* [NR: Non-Rules and myths](#s-not) +* [RF: References](#s-references) +* [Pro: Profiles](#s-profile) * [GSL: Guidelines support library](#gsl-guidelines-support-library) -* [NL: Naming and layout suggestions](#S-naming) -* [FAQ: Answers to frequently asked questions](#S-faq) -* [Appendix A: Libraries](#S-libraries) -* [Appendix B: Modernizing code](#S-modernizing) -* [Appendix C: Discussion](#S-discussion) -* [Appendix D: Supporting tools](#S-tools) -* [Glossary](#S-glossary) -* [To-do: Unclassified proto-rules](#S-unclassified) +* [NL: Naming and layout suggestions](#s-naming) +* [FAQ: Answers to frequently asked questions](#s-faq) +* [Appendix A: Libraries](#s-libraries) +* [Appendix B: Modernizing code](#s-modernizing) +* [Appendix C: Discussion](#s-discussion) +* [Appendix D: Supporting tools](#s-tools) +* [Glossary](#s-glossary) +* [To-do: Unclassified proto-rules](#s-unclassified) You can sample rules for specific language features: * assignment: -[regular types](#Rc-regular) -- -[prefer initialization](#Rc-initialize) -- -[copy](#Rc-copy-semantic) -- -[move](#Rc-move-semantic) -- -[other operations](#Rc-matched) -- -[default](#Rc-eqdefault) +[regular types](#rc-regular) -- +[prefer initialization](#rc-initialize) -- +[copy](#rc-copy-semantic) -- +[move](#rc-move-semantic) -- +[other operations](#rc-matched) -- +[default](#rc-eqdefault) * `class`: -[data](#Rc-org) -- -[invariant](#Rc-struct) -- -[members](#Rc-member) -- -[helpers](#Rc-helper) -- -[concrete types](#SS-concrete) -- -[ctors, =, and dtors](#S-ctor) -- -[hierarchy](#SS-hier) -- -[operators](#SS-overload) +[data](#rc-org) -- +[invariant](#rc-struct) -- +[members](#rc-member) -- +[helpers](#rc-helper) -- +[concrete types](#ss-concrete) -- +[ctors, =, and dtors](#s-ctor) -- +[hierarchy](#ss-hier) -- +[operators](#ss-overload) * `concept`: -[rules](#SS-concepts) -- -[in generic programming](#Rt-raise) -- -[template arguments](#Rt-concepts) -- -[semantics](#Rt-low) +[rules](#ss-concepts) -- +[in generic programming](#rt-raise) -- +[template arguments](#rt-concepts) -- +[semantics](#rt-low) * constructor: -[invariant](#Rc-struct) -- -[establish invariant](#Rc-ctor) -- -[`throw`](#Rc-throw) -- -[default](#Rc-default0) -- -[not needed](#Rc-default) -- -[`explicit`](#Rc-explicit) -- -[delegating](#Rc-delegating) -- -[`virtual`](#Rc-ctor-virtual) +[invariant](#rc-struct) -- +[establish invariant](#rc-ctor) -- +[`throw`](#rc-throw) -- +[default](#rc-default0) -- +[not needed](#rc-default) -- +[`explicit`](#rc-explicit) -- +[delegating](#rc-delegating) -- +[`virtual`](#rc-ctor-virtual) * derived `class`: -[when to use](#Rh-domain) -- -[as interface](#Rh-abstract) -- -[destructors](#Rh-dtor) -- -[copy](#Rh-copy) -- -[getters and setters](#Rh-get) -- -[multiple inheritance](#Rh-mi-interface) -- -[overloading](#Rh-using) -- -[slicing](#Rc-copy-virtual) -- -[`dynamic_cast`](#Rh-dynamic_cast) +[when to use](#rh-domain) -- +[as interface](#rh-abstract) -- +[destructors](#rh-dtor) -- +[copy](#rh-copy) -- +[getters and setters](#rh-get) -- +[multiple inheritance](#rh-mi-interface) -- +[overloading](#rh-using) -- +[slicing](#rc-copy-virtual) -- +[`dynamic_cast`](#rh-dynamic_cast) * destructor: -[and constructors](#Rc-matched) -- -[when needed?](#Rc-dtor) -- -[must not fail](#Rc-dtor-fail) +[and constructors](#rc-matched) -- +[when needed?](#rc-dtor) -- +[must not fail](#rc-dtor-fail) * exception: -[errors](#S-errors) -- -[`throw`](#Re-throw) -- -[for errors only](#Re-errors) -- -[`noexcept`](#Re-noexcept) -- -[minimize `try`](#Re-catch) -- -[what if no exceptions?](#Re-no-throw-codes) +[errors](#s-errors) -- +[`throw`](#re-throw) -- +[for errors only](#re-errors) -- +[`noexcept`](#re-noexcept) -- +[minimize `try`](#re-catch) -- +[what if no exceptions?](#re-no-throw-codes) * `for`: -[range-for and for](#Res-for-range) -- -[for and while](#Res-for-while) -- -[for-initializer](#Res-for-init) -- -[empty body](#Res-empty) -- -[loop variable](#Res-loop-counter) -- -[loop variable type ???](#Res-???) +[range-for and for](#res-for-range) -- +[for and while](#res-for-while) -- +[for-initializer](#res-for-init) -- +[empty body](#res-empty) -- +[loop variable](#res-loop-counter) -- +[loop variable type ???](#res-???) * function: -[naming](#Rf-package) -- -[single operation](#Rf-logical) -- -[no throw](#Rf-noexcept) -- -[arguments](#Rf-smart) -- -[argument passing](#Rf-conventional) -- -[multiple return values](#Rf-out-multi) -- -[pointers](#Rf-return-ptr) -- -[lambdas](#Rf-capture-vs-overload) +[naming](#rf-package) -- +[single operation](#rf-logical) -- +[no throw](#rf-noexcept) -- +[arguments](#rf-smart) -- +[argument passing](#rf-conventional) -- +[multiple return values](#rf-out-multi) -- +[pointers](#rf-return-ptr) -- +[lambdas](#rf-capture-vs-overload) * `inline`: -[small functions](#Rf-inline) -- -[in headers](#Rs-inline) +[small functions](#rf-inline) -- +[in headers](#rs-inline) * initialization: -[always](#Res-always) -- -[prefer `{}`](#Res-list) -- -[lambdas](#Res-lambda-init) -- -[default member initializers](#Rc-in-class-initializer) -- -[class members](#Rc-initialize) -- -[factory functions](#Rc-factory) +[always](#res-always) -- +[prefer `{}`](#res-list) -- +[lambdas](#res-lambda-init) -- +[default member initializers](#rc-in-class-initializer) -- +[class members](#rc-initialize) -- +[factory functions](#rc-factory) * lambda expression: -[when to use](#SS-lambdas) +[when to use](#ss-lambdas) * operator: -[conventional](#Ro-conventional) -- -[avoid conversion operators](#Ro-conversion) -- -[and lambdas](#Ro-lambda) +[conventional](#ro-conventional) -- +[avoid conversion operators](#ro-conversion) -- +[and lambdas](#ro-lambda) * `public`, `private`, and `protected`: -[information hiding](#Rc-private) -- -[consistency](#Rh-public) -- -[`protected`](#Rh-protected) +[information hiding](#rc-private) -- +[consistency](#rh-public) -- +[`protected`](#rh-protected) * `static_assert`: -[compile-time checking](#Rp-compile-time) -- -[and concepts](#Rt-check-class) +[compile-time checking](#rp-compile-time) -- +[and concepts](#rt-check-class) * `struct`: -[for organizing data](#Rc-org) -- -[use if no invariant](#Rc-struct) -- -[no private members](#Rc-class) +[for organizing data](#rc-org) -- +[use if no invariant](#rc-struct) -- +[no private members](#rc-class) * `template`: -[abstraction](#Rt-raise) -- -[containers](#Rt-cont) -- -[concepts](#Rt-concepts) +[abstraction](#rt-raise) -- +[containers](#rt-cont) -- +[concepts](#rt-concepts) * `unsigned`: -[and signed](#Res-mix) -- -[bit manipulation](#Res-unsigned) +[and signed](#res-mix) -- +[bit manipulation](#res-unsigned) * `virtual`: -[interfaces](#Ri-abstract) -- -[not `virtual`](#Rc-concrete) -- -[destructor](#Rc-dtor-virtual) -- -[never fail](#Rc-dtor-fail) +[interfaces](#ri-abstract) -- +[not `virtual`](#rc-concrete) -- +[destructor](#rc-dtor-virtual) -- +[never fail](#rc-dtor-fail) You can look at design concepts used to express the rules: @@ -182,7 +182,7 @@ You can look at design concepts used to express the rules: * postcondition: ??? * resource: ??? -# Abstract +# Abstract This document is a set of guidelines for using C++ well. The aim of this document is to help people to use modern C++ effectively. @@ -221,25 +221,25 @@ We plan to build tools for that and hope others will too. Comments and suggestions for improvements are most welcome. We plan to modify and extend this document as our understanding improves and the language and the set of available libraries improve. -# In: Introduction +# In: Introduction This is a set of core guidelines for modern C++ (currently C++20 and C++17) taking likely future enhancements and ISO Technical Specifications (TSs) into account. The aim is to help C++ programmers to write simpler, more efficient, more maintainable code. Introduction summary: -* [In.target: Target readership](#SS-readers) -* [In.aims: Aims](#SS-aims) -* [In.not: Non-aims](#SS-non) -* [In.force: Enforcement](#SS-force) -* [In.struct: The structure of this document](#SS-struct) -* [In.sec: Major sections](#SS-sec) +* [In.target: Target readership](#ss-readers) +* [In.aims: Aims](#ss-aims) +* [In.not: Non-aims](#ss-non) +* [In.force: Enforcement](#ss-force) +* [In.struct: The structure of this document](#ss-struct) +* [In.sec: Major sections](#ss-sec) -## In.target: Target readership +## In.target: Target readership -All C++ programmers. This includes [programmers who might consider C](#S-cpl). +All C++ programmers. This includes [programmers who might consider C](#s-cpl). -## In.aims: Aims +## In.aims: Aims The purpose of this document is to help developers to adopt modern C++ (currently C++20 and C++17) and to achieve a more uniform style across code bases. @@ -248,7 +248,7 @@ As far as we can tell, these rules lead to code that performs as well or better Consider these rules ideals for new code, opportunities to exploit when working on older code, and try to approximate these ideals as closely as feasible. Remember: -### In.0: Don't panic! +### In.0: Don't panic! Take the time to understand the implications of a guideline rule on your program. @@ -272,13 +272,13 @@ For example, hard-real-time programmers typically can't use free store (dynamic We encourage the development of such more specific rules as addenda to these core guidelines. Build your ideal small foundation library and use that, rather than lowering your level of programming to glorified assembly code. -The rules are designed to allow [gradual adoption](#S-modernizing). +The rules are designed to allow [gradual adoption](#s-modernizing). Some rules aim to increase various forms of safety while others aim to reduce the likelihood of accidents, many do both. The guidelines aimed at preventing accidents often ban perfectly legal C++. However, when there are two ways of expressing an idea and one has shown itself a common source of errors and the other has not, we try to guide programmers towards the latter. -## In.not: Non-aims +## In.not: Non-aims The rules are not intended to be minimal or orthogonal. In particular, general rules can be simple, but unenforceable. @@ -294,11 +294,11 @@ That is, a tool looks for violations and the tool returns links to violated rule The rules then provide reasons, examples of potential consequences of the violation, and suggested remedies. These guidelines are not intended to be a substitute for a tutorial treatment of C++. -If you need a tutorial for some given level of experience, see [the references](#S-references). +If you need a tutorial for some given level of experience, see [the references](#s-references). This is not a guide on how to convert old C++ code to more modern code. It is meant to articulate ideas for new code in a concrete fashion. -However, see [the modernization section](#S-modernizing) for some possible approaches to modernizing/rejuvenating/upgrading. +However, see [the modernization section](#s-modernizing) for some possible approaches to modernizing/rejuvenating/upgrading. Importantly, the rules support gradual adoption: It is typically infeasible to completely convert a large code base all at once. These guidelines are not meant to be complete or exact in every language-technical detail. @@ -328,7 +328,7 @@ Instead, our aim is the less ambitious: "Do the most good for most programmers"; if you cannot live with a rule, object to it, ignore it, but don't water it down until it becomes meaningless. Also, suggest an improvement. -## In.force: Enforcement +## In.force: Enforcement Rules with no enforcement are unmanageable for large code bases. Enforcement of all rules is possible only for a small weak set of rules or for a specific user community. @@ -373,13 +373,13 @@ and optionally with a message (following usual C++11 standard attribute syntax): where -* `"tag"` is a string literal with the anchor name of the item where the Enforcement rule appears (e.g., for [C.134](#Rh-public) it is "Rh-public"), the +* `"tag"` is a string literal with the anchor name of the item where the Enforcement rule appears (e.g., for [C.134](#rh-public) it is "rh-public"), the name of a profile group-of-rules ("type", "bounds", or "lifetime"), -or a specific rule in a profile ([type.4](#Pro-type-cstylecast), or [bounds.2](#Pro-bounds-arrayindex)). Any text that is not one of those should be rejected. +or a specific rule in a profile ([type.4](#pro-type-cstylecast), or [bounds.2](#pro-bounds-arrayindex)). Any text that is not one of those should be rejected. * `"message"` is a string literal -## In.struct: The structure of this document +## In.struct: The structure of this document Each rule (guideline, suggestion) can have several parts: @@ -401,7 +401,7 @@ We hope that "mechanical" tools will improve with time to approximate what such Also, we assume that the rules will be refined over time to make them more precise and checkable. A rule is aimed at being simple, rather than carefully phrased to mention every alternative and special case. -Such information is found in the **Alternative** paragraphs and the [Discussion](#S-discussion) sections. +Such information is found in the **Alternative** paragraphs and the [Discussion](#s-discussion) sections. If you don't understand a rule or disagree with it, please visit its **Discussion**. If you feel that a discussion is missing or incomplete, enter an [Issue](https://github.com/isocpp/CppCoreGuidelines/issues) explaining your concerns and possibly a corresponding PR. @@ -416,73 +416,73 @@ For example, many examples are language-technical and use names like `f`, `base` This is not a language manual. It is meant to be helpful, rather than complete, fully accurate on technical details, or a guide to existing code. -Recommended information sources can be found in [the references](#S-references). - -## In.sec: Major sections - -* [In: Introduction](#S-introduction) -* [P: Philosophy](#S-philosophy) -* [I: Interfaces](#S-interfaces) -* [F: Functions](#S-functions) -* [C: Classes and class hierarchies](#S-class) -* [Enum: Enumerations](#S-enum) -* [R: Resource management](#S-resource) -* [ES: Expressions and statements](#S-expr) -* [Per: Performance](#S-performance) -* [CP: Concurrency and parallelism](#S-concurrency) -* [E: Error handling](#S-errors) -* [Con: Constants and immutability](#S-const) -* [T: Templates and generic programming](#S-templates) -* [CPL: C-style programming](#S-cpl) -* [SF: Source files](#S-source) +Recommended information sources can be found in [the references](#s-references). + +## In.sec: Major sections + +* [In: Introduction](#s-introduction) +* [P: Philosophy](#s-philosophy) +* [I: Interfaces](#s-interfaces) +* [F: Functions](#s-functions) +* [C: Classes and class hierarchies](#s-class) +* [Enum: Enumerations](#s-enum) +* [R: Resource management](#s-resource) +* [ES: Expressions and statements](#s-expr) +* [Per: Performance](#s-performance) +* [CP: Concurrency and parallelism](#s-concurrency) +* [E: Error handling](#s-errors) +* [Con: Constants and immutability](#s-const) +* [T: Templates and generic programming](#s-templates) +* [CPL: C-style programming](#s-cpl) +* [SF: Source files](#s-source) * [SL: The Standard Library](#sl-the-standard-library) Supporting sections: -* [A: Architectural ideas](#S-A) -* [NR: Non-Rules and myths](#S-not) -* [RF: References](#S-references) -* [Pro: Profiles](#S-profile) +* [A: Architectural ideas](#s-a) +* [NR: Non-Rules and myths](#s-not) +* [RF: References](#s-references) +* [Pro: Profiles](#s-profile) * [GSL: Guidelines support library](#gsl-guidelines-support-library) -* [NL: Naming and layout suggestions](#S-naming) -* [FAQ: Answers to frequently asked questions](#S-faq) -* [Appendix A: Libraries](#S-libraries) -* [Appendix B: Modernizing code](#S-modernizing) -* [Appendix C: Discussion](#S-discussion) -* [Appendix D: Supporting tools](#S-tools) -* [Glossary](#S-glossary) -* [To-do: Unclassified proto-rules](#S-unclassified) +* [NL: Naming and layout suggestions](#s-naming) +* [FAQ: Answers to frequently asked questions](#s-faq) +* [Appendix A: Libraries](#s-libraries) +* [Appendix B: Modernizing code](#s-modernizing) +* [Appendix C: Discussion](#s-discussion) +* [Appendix D: Supporting tools](#s-tools) +* [Glossary](#s-glossary) +* [To-do: Unclassified proto-rules](#s-unclassified) These sections are not orthogonal. Each section (e.g., "P" for "Philosophy") and each subsection (e.g., "C.hier" for "Class Hierarchies (OOP)") have an abbreviation for ease of searching and reference. The main section abbreviations are also used in rule numbers (e.g., "C.11" for "Make concrete types regular"). -# P: Philosophy +# P: Philosophy The rules in this section are very general. Philosophy rules summary: -* [P.1: Express ideas directly in code](#Rp-direct) -* [P.2: Write in ISO Standard C++](#Rp-Cplusplus) -* [P.3: Express intent](#Rp-what) -* [P.4: Ideally, a program should be statically type safe](#Rp-typesafe) -* [P.5: Prefer compile-time checking to run-time checking](#Rp-compile-time) -* [P.6: What cannot be checked at compile time should be checkable at run time](#Rp-run-time) -* [P.7: Catch run-time errors early](#Rp-early) -* [P.8: Don't leak any resources](#Rp-leak) -* [P.9: Don't waste time or space](#Rp-waste) -* [P.10: Prefer immutable data to mutable data](#Rp-mutable) -* [P.11: Encapsulate messy constructs, rather than spreading through the code](#Rp-library) -* [P.12: Use supporting tools as appropriate](#Rp-tools) -* [P.13: Use support libraries as appropriate](#Rp-lib) +* [P.1: Express ideas directly in code](#rp-direct) +* [P.2: Write in ISO Standard C++](#rp-cplusplus) +* [P.3: Express intent](#rp-what) +* [P.4: Ideally, a program should be statically type safe](#rp-typesafe) +* [P.5: Prefer compile-time checking to run-time checking](#rp-compile-time) +* [P.6: What cannot be checked at compile time should be checkable at run time](#rp-run-time) +* [P.7: Catch run-time errors early](#rp-early) +* [P.8: Don't leak any resources](#rp-leak) +* [P.9: Don't waste time or space](#rp-waste) +* [P.10: Prefer immutable data to mutable data](#rp-mutable) +* [P.11: Encapsulate messy constructs, rather than spreading through the code](#rp-library) +* [P.12: Use supporting tools as appropriate](#rp-tools) +* [P.13: Use support libraries as appropriate](#rp-lib) Philosophical rules are generally not mechanically checkable. However, individual rules reflecting these philosophical themes are. Without a philosophical basis, the more concrete/specific/checkable rules lack rationale. -### P.1: Express ideas directly in code +### P.1: Express ideas directly in code ##### Reason @@ -563,7 +563,7 @@ Very hard in general. * flag uses of casts (casts neuter the type system) * detect code that mimics the standard library (hard) -### P.2: Write in ISO Standard C++ +### P.2: Write in ISO Standard C++ ##### Reason @@ -583,7 +583,7 @@ portability will be impacted. ##### Note Using valid ISO C++ does not guarantee portability (let alone correctness). -Avoid dependence on undefined behavior (e.g., [undefined order of evaluation](#Res-order)) +Avoid dependence on undefined behavior (e.g., [undefined order of evaluation](#res-order)) and be aware of constructs with implementation defined meaning (e.g., `sizeof(int)`). ##### Note @@ -595,7 +595,7 @@ In such cases, control their (dis)use with an extension of these Coding Guidelin Use an up-to-date C++ compiler (currently C++20 or C++17) with a set of options that do not accept extensions. -### P.3: Express intent +### P.3: Express intent ##### Reason @@ -618,7 +618,7 @@ Now, there is no explicit mention of the iteration mechanism, and the loop opera for (auto& x : v) { /* modify x */ } -For more details about for-statements, see [ES.71](#Res-for-range). +For more details about for-statements, see [ES.71](#res-for-range). Sometimes better still, use a named algorithm. This example uses the `for_each` from the Ranges TS because it directly expresses the intent: for_each(v, [](int x) { /* do something with the value of x */ }); @@ -661,7 +661,7 @@ Look for common patterns for which there are better alternatives There is a huge scope for cleverness and semi-automated program transformation. -### P.4: Ideally, a program should be statically type safe +### P.4: Ideally, a program should be statically type safe ##### Reason @@ -691,7 +691,7 @@ For example: * range errors -- use `span` * narrowing conversions -- minimize their use and use `narrow` or `narrow_cast` (from the GSL) where they are necessary -### P.5: Prefer compile-time checking to run-time checking +### P.5: Prefer compile-time checking to run-time checking ##### Reason @@ -735,7 +735,7 @@ better * Look for pointer arguments. * Look for run-time checks for range violations. -### P.6: What cannot be checked at compile time should be checkable at run time +### P.6: What cannot be checked at compile time should be checkable at run time ##### Reason @@ -842,7 +842,7 @@ How do we transfer both ownership and all information needed for validating use? * Flag (pointer, count)-style interfaces (this will flag a lot of examples that can't be fixed for compatibility reasons) * ??? -### P.7: Catch run-time errors early +### P.7: Catch run-time errors early ##### Reason @@ -959,7 +959,7 @@ The physical law for a jet (`e * e < x * x + y * y + z * z`) is not an invariant * Look for structured data (objects of classes with invariants) being converted into strings * ??? -### P.8: Don't leak any resources +### P.8: Don't leak any resources ##### Reason @@ -977,7 +977,7 @@ This is particularly important for long-running programs, but is an essential pi fclose(input); } -Prefer [RAII](#Rr-raii): +Prefer [RAII](#rr-raii): void f(char* name) { @@ -987,7 +987,7 @@ Prefer [RAII](#Rr-raii): // ... } -**See also**: [The resource management section](#S-resource) +**See also**: [The resource management section](#s-resource) ##### Note @@ -1000,9 +1000,9 @@ However, relying on abstractions that implicitly clean up can be as simple, and ##### Note -Enforcing [the lifetime safety profile](#SS-lifetime) eliminates leaks. -When combined with resource safety provided by [RAII](#Rr-raii), it eliminates the need for "garbage collection" (by generating no garbage). -Combine this with enforcement of [the type and bounds profiles](#SS-force) and you get complete type- and resource-safety, guaranteed by tools. +Enforcing [the lifetime safety profile](#ss-lifetime) eliminates leaks. +When combined with resource safety provided by [RAII](#rr-raii), it eliminates the need for "garbage collection" (by generating no garbage). +Combine this with enforcement of [the type and bounds profiles](#ss-force) and you get complete type- and resource-safety, guaranteed by tools. ##### Enforcement @@ -1012,7 +1012,7 @@ Combine this with enforcement of [the type and bounds profiles](#SS-force) and y * Look for naked `new` and `delete` * Look for known resource allocating functions returning raw pointers (such as `fopen`, `malloc`, and `strdup`) -### P.9: Don't waste time or space +### P.9: Don't waste time or space ##### Reason @@ -1088,7 +1088,7 @@ Many more specific rules aim at the overall goals of simplicity and elimination * Flag an unused return value from a user-defined non-defaulted postfix `operator++` or `operator--` function. Prefer using the prefix form instead. (Note: "User-defined non-defaulted" is intended to reduce noise. Review this enforcement if it's still too noisy in practice.) -### P.10: Prefer immutable data to mutable data +### P.10: Prefer immutable data to mutable data ##### Reason @@ -1097,9 +1097,9 @@ Something immutable cannot change unexpectedly. Sometimes immutability enables better optimization. You can't have a data race on a constant. -See [Con: Constants and immutability](#S-const) +See [Con: Constants and immutability](#s-const) -### P.11: Encapsulate messy constructs, rather than spreading through the code +### P.11: Encapsulate messy constructs, rather than spreading through the code ##### Reason @@ -1142,14 +1142,14 @@ that are needed to implement key abstractions, such as `vector`, `span`, `lock_g designed and implemented by people with more time and expertise than we usually have. Similarly, we can and should design and implement more specialized libraries, rather than leaving the users (often ourselves) with the challenge of repeatedly getting low-level code well. -This is a variant of the [subset of superset principle](#R0) that underlies these guidelines. +This is a variant of the [subset of superset principle](#r0) that underlies these guidelines. ##### Enforcement * Look for "messy code" such as complex pointer manipulation and casting outside the implementation of abstractions. -### P.12: Use supporting tools as appropriate +### P.12: Use supporting tools as appropriate ##### Reason @@ -1166,7 +1166,7 @@ Run a static analyzer to verify that your code follows the guidelines you want i See * [Static analysis tools](https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis) -* [Concurrency tools](#Rconc-tools) +* [Concurrency tools](#rconc-tools) * [Testing tools](https://github.com/isocpp/CppCoreGuidelines/tree/master) There are many other kinds of tools, such as source code repositories, build tools, etc., @@ -1178,7 +1178,7 @@ Be careful not to become dependent on over-elaborate or over-specialized tool ch Those can make your otherwise portable code non-portable. -### P.13: Use support libraries as appropriate +### P.13: Use support libraries as appropriate ##### Reason @@ -1211,45 +1211,45 @@ If no well-designed, well-documented, and well-supported library exists for an i maybe you should design and implement it, and then use it. -# I: Interfaces +# I: Interfaces An interface is a contract between two parts of a program. Precisely stating what is expected of a supplier of a service and a user of that service is essential. Having good (easy-to-understand, encouraging efficient use, not error-prone, supporting testing, etc.) interfaces is probably the most important single aspect of code organization. Interface rule summary: -* [I.1: Make interfaces explicit](#Ri-explicit) -* [I.2: Avoid non-`const` global variables](#Ri-global) -* [I.3: Avoid singletons](#Ri-singleton) -* [I.4: Make interfaces precisely and strongly typed](#Ri-typed) -* [I.5: State preconditions (if any)](#Ri-pre) -* [I.6: Prefer `Expects()` for expressing preconditions](#Ri-expects) -* [I.7: State postconditions](#Ri-post) -* [I.8: Prefer `Ensures()` for expressing postconditions](#Ri-ensures) -* [I.9: If an interface is a template, document its parameters using concepts](#Ri-concepts) -* [I.10: Use exceptions to signal a failure to perform a required task](#Ri-except) -* [I.11: Never transfer ownership by a raw pointer (`T*`) or reference (`T&`)](#Ri-raw) -* [I.12: Declare a pointer that must not be null as `not_null`](#Ri-nullptr) -* [I.13: Do not pass an array as a single pointer](#Ri-array) -* [I.22: Avoid complex initialization of global objects](#Ri-global-init) -* [I.23: Keep the number of function arguments low](#Ri-nargs) -* [I.24: Avoid adjacent parameters that can be invoked by the same arguments in either order with different meaning](#Ri-unrelated) -* [I.25: Prefer empty abstract classes as interfaces to class hierarchies](#Ri-abstract) -* [I.26: If you want a cross-compiler ABI, use a C-style subset](#Ri-abi) -* [I.27: For stable library ABI, consider the Pimpl idiom](#Ri-pimpl) -* [I.30: Encapsulate rule violations](#Ri-encapsulate) +* [I.1: Make interfaces explicit](#ri-explicit) +* [I.2: Avoid non-`const` global variables](#ri-global) +* [I.3: Avoid singletons](#ri-singleton) +* [I.4: Make interfaces precisely and strongly typed](#ri-typed) +* [I.5: State preconditions (if any)](#ri-pre) +* [I.6: Prefer `Expects()` for expressing preconditions](#ri-expects) +* [I.7: State postconditions](#ri-post) +* [I.8: Prefer `Ensures()` for expressing postconditions](#ri-ensures) +* [I.9: If an interface is a template, document its parameters using concepts](#ri-concepts) +* [I.10: Use exceptions to signal a failure to perform a required task](#ri-except) +* [I.11: Never transfer ownership by a raw pointer (`T*`) or reference (`T&`)](#ri-raw) +* [I.12: Declare a pointer that must not be null as `not_null`](#ri-nullptr) +* [I.13: Do not pass an array as a single pointer](#ri-array) +* [I.22: Avoid complex initialization of global objects](#ri-global-init) +* [I.23: Keep the number of function arguments low](#ri-nargs) +* [I.24: Avoid adjacent parameters that can be invoked by the same arguments in either order with different meaning](#ri-unrelated) +* [I.25: Prefer empty abstract classes as interfaces to class hierarchies](#ri-abstract) +* [I.26: If you want a cross-compiler ABI, use a C-style subset](#ri-abi) +* [I.27: For stable library ABI, consider the Pimpl idiom](#ri-pimpl) +* [I.30: Encapsulate rule violations](#ri-encapsulate) **See also**: -* [F: Functions](#S-functions) -* [C.concrete: Concrete types](#SS-concrete) -* [C.hier: Class hierarchies](#SS-hier) -* [C.over: Overloading and overloaded operators](#SS-overload) -* [C.con: Containers and other resource handles](#SS-containers) -* [E: Error handling](#S-errors) -* [T: Templates and generic programming](#S-templates) +* [F: Functions](#s-functions) +* [C.concrete: Concrete types](#ss-concrete) +* [C.hier: Class hierarchies](#ss-hier) +* [C.over: Overloading and overloaded operators](#ss-overload) +* [C.con: Containers and other resource handles](#ss-containers) +* [E: Error handling](#s-errors) +* [T: Templates and generic programming](#s-templates) -### I.1: Make interfaces explicit +### I.1: Make interfaces explicit ##### Reason @@ -1293,7 +1293,7 @@ Functions can be function templates and sets of functions can be classes or clas * (Simple) A function should not make control-flow decisions based on the values of variables declared at namespace scope. * (Simple) A function should not write to variables declared at namespace scope. -### I.2: Avoid non-`const` global variables +### I.2: Avoid non-`const` global variables ##### Reason @@ -1346,7 +1346,7 @@ data isn't a better alternative to non-const global variables since that doesn't You cannot have a race condition on immutable data. -**References**: See the [rules for calling functions](#SS-call). +**References**: See the [rules for calling functions](#ss-call). ##### Note @@ -1357,7 +1357,7 @@ The rule is "avoid", not "don't use." Of course there will be (rare) exceptions, (Simple) Report all non-`const` variables declared at namespace scope and global pointers/references to non-const data. -### I.3: Avoid singletons +### I.3: Avoid singletons ##### Reason @@ -1418,7 +1418,7 @@ Very hard in general. * Look for classes for which only a single object is created (by counting objects or by examining constructors). * If a class X has a public static function that contains a function-local static of the class' type X and returns a pointer or reference to it, ban that. -### I.4: Make interfaces precisely and strongly typed +### I.4: Make interfaces precisely and strongly typed ##### Reason @@ -1540,7 +1540,7 @@ The function can also be written in such a way that it will accept any time dura * (Simple) Report the use of more than one `bool` parameter. * (Hard to do well) Look for functions that use too many primitive type arguments. -### I.5: State preconditions (if any) +### I.5: State preconditions (if any) ##### Reason @@ -1581,7 +1581,7 @@ We don't need to mention it for each member function. **See also**: The rules for passing pointers. ??? -### I.6: Prefer `Expects()` for expressing preconditions +### I.6: Prefer `Expects()` for expressing preconditions ##### Reason @@ -1613,13 +1613,13 @@ Once language support becomes available (e.g., see the [contract proposal](http: ##### Note -No, using `unsigned` is not a good way to sidestep the problem of [ensuring that a value is non-negative](#Res-nonnegative). +No, using `unsigned` is not a good way to sidestep the problem of [ensuring that a value is non-negative](#res-nonnegative). ##### Enforcement (Not enforceable) Finding the variety of ways preconditions can be asserted is not feasible. Warning about those that can be easily identified (`assert()`) has questionable value in the absence of a language facility. -### I.7: State postconditions +### I.7: State postconditions ##### Reason @@ -1695,7 +1695,7 @@ Stating the postcondition would have made it clear: The bug is now obvious (but only to a human reading comments). -Better still, use [RAII](#Rr-raii) to ensure that the postcondition ("the lock must be released") is enforced in code: +Better still, use [RAII](#rr-raii) to ensure that the postcondition ("the lock must be released") is enforced in code: void manipulate(Record& r) // best { @@ -1715,7 +1715,7 @@ Postconditions related only to internal state belong in the definition/implement directly in the general case. Domain specific checkers (like lock-holding checkers) exist for many toolchains. -### I.8: Prefer `Ensures()` for expressing postconditions +### I.8: Prefer `Ensures()` for expressing postconditions ##### Reason @@ -1736,7 +1736,7 @@ To make it clear that the condition is a postcondition and to enable tool use. Postconditions can be stated in many ways, including comments, `if`-statements, and `assert()`. This can make them hard to distinguish from ordinary code, hard to update, hard to manipulate by tools, and might have the wrong semantics. -**Alternative**: Postconditions of the form "this resource must be released" are best expressed by [RAII](#Rr-raii). +**Alternative**: Postconditions of the form "this resource must be released" are best expressed by [RAII](#rr-raii). ##### Note @@ -1748,7 +1748,7 @@ Once language support becomes available (e.g., see the [contract proposal](http: (Not enforceable) Finding the variety of ways postconditions can be asserted is not feasible. Warning about those that can be easily identified (`assert()`) has questionable value in the absence of a language facility. -### I.9: If an interface is a template, document its parameters using concepts +### I.9: If an interface is a template, document its parameters using concepts ##### Reason @@ -1765,13 +1765,13 @@ Use the C++20 style of requirements specification. For example: // ... } -**See also**: [Generic programming](#SS-GP) and [concepts](#SS-concepts). +**See also**: [Generic programming](#ss-gp) and [concepts](#ss-concepts). ##### Enforcement Warn if any non-variadic template parameter is not constrained by a concept (in its declaration or mentioned in a `requires` clause). -### I.10: Use exceptions to signal a failure to perform a required task +### I.10: Use exceptions to signal a failure to perform a required task ##### Reason @@ -1827,18 +1827,18 @@ We don't consider "performance" a valid reason not to use exceptions. * Often, explicit error checking and handling consume as much time and space as exception handling. * Often, cleaner code yields better performance with exceptions (simplifying the tracing of paths through the program and their optimization). -* A good rule for performance critical code is to move checking outside the [critical](#Rper-critical) part of the code. +* A good rule for performance critical code is to move checking outside the [critical](#rper-critical) part of the code. * In the longer term, more regular code gets better optimized. -* Always carefully [measure](#Rper-measure) before making performance claims. +* Always carefully [measure](#rper-measure) before making performance claims. -**See also**: [I.5](#Ri-pre) and [I.7](#Ri-post) for reporting precondition and postcondition violations. +**See also**: [I.5](#ri-pre) and [I.7](#ri-post) for reporting precondition and postcondition violations. ##### Enforcement * (Not enforceable) This is a philosophical guideline that is infeasible to check directly. * Look for `errno`. -### I.11: Never transfer ownership by a raw pointer (`T*`) or reference (`T&`) +### I.11: Never transfer ownership by a raw pointer (`T*`) or reference (`T&`) ##### Reason @@ -1865,7 +1865,7 @@ Consider returning the result by value (use move semantics if the result is larg return res; } -**Alternative**: [Pass ownership](#Rr-smartptrparam) using a "smart pointer", such as `unique_ptr` (for exclusive ownership) and `shared_ptr` (for shared ownership). +**Alternative**: [Pass ownership](#rr-smartptrparam) using a "smart pointer", such as `unique_ptr` (for exclusive ownership) and `shared_ptr` (for shared ownership). However, that is less elegant and often less efficient than returning the object itself, so use smart pointers only if reference semantics are needed. @@ -1891,7 +1891,7 @@ caller, so that its lifetime is handled by the caller. Viewed another way: ownership transferring APIs are relatively rare compared to pointer-passing APIs, so the default is "no ownership transfer." -**See also**: [Argument passing](#Rf-conventional), [use of smart pointer arguments](#Rr-smartptrparam), and [value return](#Rf-value-return). +**See also**: [Argument passing](#rf-conventional), [use of smart pointer arguments](#rr-smartptrparam), and [value return](#rf-value-return). ##### Enforcement @@ -1899,7 +1899,7 @@ so the default is "no ownership transfer." * (Simple) Warn on failure to either `reset` or explicitly `delete` an `owner` pointer on every code path. * (Simple) Warn if the return value of `new` or a function call with an `owner` return value is assigned to a raw pointer or non-`owner` reference. -### I.12: Declare a pointer that must not be null as `not_null` +### I.12: Declare a pointer that must not be null as `not_null` ##### Reason @@ -1937,7 +1937,7 @@ Note: `length()` is, of course, `std::strlen()` in disguise. * (Simple) ((Foundation)) If a function checks a pointer parameter against `nullptr` before access, on all control-flow paths, then warn it should be declared `not_null`. * (Complex) If a function with pointer return value ensures it is not `nullptr` on all return paths, then warn the return type should be declared `not_null`. -### I.13: Do not pass an array as a single pointer +### I.13: Do not pass an array as a single pointer ##### Reason @@ -1993,7 +1993,7 @@ But when doing so, use `std::string_view` or `span` from the [GSL](#gsl-gu * (Simple) ((Bounds)) Warn for any expression that would rely on implicit conversion of an array type to a pointer type. Allow exception for zstring/czstring pointer types. * (Simple) ((Bounds)) Warn for any arithmetic operation on an expression of pointer type that results in a value of pointer type. Allow exception for zstring/czstring pointer types. -### I.22: Avoid complex initialization of global objects +### I.22: Avoid complex initialization of global objects ##### Reason @@ -2027,7 +2027,7 @@ It is usually best to avoid global (namespace scope) objects altogether. * Flag initializers of globals that call non-`constexpr` functions * Flag initializers of globals that access `extern` objects -### I.23: Keep the number of function arguments low +### I.23: Keep the number of function arguments low ##### Reason @@ -2105,7 +2105,7 @@ There are functions that are best expressed with four individual parameters, but * Warn when a function declares two iterators (including pointers) of the same type instead of a range or a view. * (Not enforceable) This is a philosophical guideline that is infeasible to check directly. -### I.24: Avoid adjacent parameters that can be invoked by the same arguments in either order with different meaning +### I.24: Avoid adjacent parameters that can be invoked by the same arguments in either order with different meaning ##### Reason @@ -2159,7 +2159,7 @@ Only the interface's designer can adequately address the source of violations of We are still looking for a less-simple enforcement. -### I.25: Prefer empty abstract classes as interfaces to class hierarchies +### I.25: Prefer empty abstract classes as interfaces to class hierarchies ##### Reason @@ -2198,7 +2198,7 @@ This will force every derived class to compute a center -- even if that's non-tr (Simple) Warn if a pointer/reference to a class `C` is assigned to a pointer/reference to a base of `C` and the base class contains data members. -### I.26: If you want a cross-compiler ABI, use a C-style subset +### I.26: If you want a cross-compiler ABI, use a C-style subset ##### Reason @@ -2216,7 +2216,7 @@ If you use a single compiler, you can use full C++ in interfaces. That might req (Not enforceable) It is difficult to reliably identify where an interface forms part of an ABI. -### I.27: For stable library ABI, consider the Pimpl idiom +### I.27: For stable library ABI, consider the Pimpl idiom ##### Reason @@ -2264,7 +2264,7 @@ See [GOTW #100](https://herbsutter.com/gotw/_100/) and [cppreference](http://en. (Not enforceable) It is difficult to reliably identify where an interface forms part of an ABI. -### I.30: Encapsulate rule violations +### I.30: Encapsulate rule violations ##### Reason @@ -2289,9 +2289,9 @@ We might write } istream& in = *inp; -This violated the rule [against uninitialized variables](#Res-always), -the rule against [ignoring ownership](#Ri-raw), -and the rule [against magic constants](#Res-magic). +This violated the rule [against uninitialized variables](#res-always), +the rule against [ignoring ownership](#ri-raw), +and the rule [against magic constants](#res-magic). In particular, someone has to remember to somewhere write if (owned) delete inp; @@ -2327,7 +2327,7 @@ Presumably, a bit of checking for potential errors would be added in real code. * Hard, it is hard to decide what rule-breaking code is essential * Flag rule suppression that enable rule-violations to cross interfaces -# F: Functions +# F: Functions A function specifies an action or a computation that takes the system from one consistent state to the next. It is the fundamental building block of programs. @@ -2338,68 +2338,68 @@ Function rule summary: Function definition rules: -* [F.1: "Package" meaningful operations as carefully named functions](#Rf-package) -* [F.2: A function should perform a single logical operation](#Rf-logical) -* [F.3: Keep functions short and simple](#Rf-single) -* [F.4: If a function might have to be evaluated at compile time, declare it `constexpr`](#Rf-constexpr) -* [F.5: If a function is very small and time-critical, declare it inline](#Rf-inline) -* [F.6: If your function must not throw, declare it `noexcept`](#Rf-noexcept) -* [F.7: For general use, take `T*` or `T&` arguments rather than smart pointers](#Rf-smart) -* [F.8: Prefer pure functions](#Rf-pure) -* [F.9: Unused parameters should be unnamed](#Rf-unused) -* [F.10: If an operation can be reused, give it a name](#Rf-name) -* [F.11: Use an unnamed lambda if you need a simple function object in one place only](#Rf-lambda) +* [F.1: "Package" meaningful operations as carefully named functions](#rf-package) +* [F.2: A function should perform a single logical operation](#rf-logical) +* [F.3: Keep functions short and simple](#rf-single) +* [F.4: If a function might have to be evaluated at compile time, declare it `constexpr`](#rf-constexpr) +* [F.5: If a function is very small and time-critical, declare it inline](#rf-inline) +* [F.6: If your function must not throw, declare it `noexcept`](#rf-noexcept) +* [F.7: For general use, take `T*` or `T&` arguments rather than smart pointers](#rf-smart) +* [F.8: Prefer pure functions](#rf-pure) +* [F.9: Unused parameters should be unnamed](#rf-unused) +* [F.10: If an operation can be reused, give it a name](#rf-name) +* [F.11: Use an unnamed lambda if you need a simple function object in one place only](#rf-lambda) Parameter passing expression rules: -* [F.15: Prefer simple and conventional ways of passing information](#Rf-conventional) -* [F.16: For "in" parameters, pass cheaply-copied types by value and others by reference to `const`](#Rf-in) -* [F.17: For "in-out" parameters, pass by reference to non-`const`](#Rf-inout) -* [F.18: For "will-move-from" parameters, pass by `X&&` and `std::move` the parameter](#Rf-consume) -* [F.19: For "forward" parameters, pass by `TP&&` and only `std::forward` the parameter](#Rf-forward) -* [F.20: For "out" output values, prefer return values to output parameters](#Rf-out) -* [F.21: To return multiple "out" values, prefer returning a struct](#Rf-out-multi) -* [F.60: Prefer `T*` over `T&` when "no argument" is a valid option](#Rf-ptr-ref) +* [F.15: Prefer simple and conventional ways of passing information](#rf-conventional) +* [F.16: For "in" parameters, pass cheaply-copied types by value and others by reference to `const`](#rf-in) +* [F.17: For "in-out" parameters, pass by reference to non-`const`](#rf-inout) +* [F.18: For "will-move-from" parameters, pass by `X&&` and `std::move` the parameter](#rf-consume) +* [F.19: For "forward" parameters, pass by `TP&&` and only `std::forward` the parameter](#rf-forward) +* [F.20: For "out" output values, prefer return values to output parameters](#rf-out) +* [F.21: To return multiple "out" values, prefer returning a struct](#rf-out-multi) +* [F.60: Prefer `T*` over `T&` when "no argument" is a valid option](#rf-ptr-ref) Parameter passing semantic rules: -* [F.22: Use `T*` or `owner` to designate a single object](#Rf-ptr) -* [F.23: Use a `not_null` to indicate that "null" is not a valid value](#Rf-nullptr) -* [F.24: Use a `span` or a `span_p` to designate a half-open sequence](#Rf-range) -* [F.25: Use a `zstring` or a `not_null` to designate a C-style string](#Rf-zstring) -* [F.26: Use a `unique_ptr` to transfer ownership where a pointer is needed](#Rf-unique_ptr) -* [F.27: Use a `shared_ptr` to share ownership](#Rf-shared_ptr) +* [F.22: Use `T*` or `owner` to designate a single object](#rf-ptr) +* [F.23: Use a `not_null` to indicate that "null" is not a valid value](#rf-nullptr) +* [F.24: Use a `span` or a `span_p` to designate a half-open sequence](#rf-range) +* [F.25: Use a `zstring` or a `not_null` to designate a C-style string](#rf-zstring) +* [F.26: Use a `unique_ptr` to transfer ownership where a pointer is needed](#rf-unique_ptr) +* [F.27: Use a `shared_ptr` to share ownership](#rf-shared_ptr) -Value return semantic rules: +Value return semantic rules: -* [F.42: Return a `T*` to indicate a position (only)](#Rf-return-ptr) -* [F.43: Never (directly or indirectly) return a pointer or a reference to a local object](#Rf-dangle) -* [F.44: Return a `T&` when copy is undesirable and "returning no object" isn't needed](#Rf-return-ref) -* [F.45: Don't return a `T&&`](#Rf-return-ref-ref) -* [F.46: `int` is the return type for `main()`](#Rf-main) -* [F.47: Return `T&` from assignment operators](#Rf-assignment-op) -* [F.48: Don't return `std::move(local)`](#Rf-return-move-local) -* [F.49: Don't return `const T`](#Rf-return-const) +* [F.42: Return a `T*` to indicate a position (only)](#rf-return-ptr) +* [F.43: Never (directly or indirectly) return a pointer or a reference to a local object](#rf-dangle) +* [F.44: Return a `T&` when copy is undesirable and "returning no object" isn't needed](#rf-return-ref) +* [F.45: Don't return a `T&&`](#rf-return-ref-ref) +* [F.46: `int` is the return type for `main()`](#rf-main) +* [F.47: Return `T&` from assignment operators](#rf-assignment-op) +* [F.48: Don't return `std::move(local)`](#rf-return-move-local) +* [F.49: Don't return `const T`](#rf-return-const) Other function rules: -* [F.50: Use a lambda when a function won't do (to capture local variables, or to write a local function)](#Rf-capture-vs-overload) -* [F.51: Where there is a choice, prefer default arguments over overloading](#Rf-default-args) -* [F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms](#Rf-reference-capture) -* [F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread](#Rf-value-capture) -* [F.54: When writing a lambda that captures `this` or any class data member, don't use `[=]` default capture](#Rf-this-capture) -* [F.55: Don't use `va_arg` arguments](#F-varargs) -* [F.56: Avoid unnecessary condition nesting](#F-nesting) +* [F.50: Use a lambda when a function won't do (to capture local variables, or to write a local function)](#rf-capture-vs-overload) +* [F.51: Where there is a choice, prefer default arguments over overloading](#rf-default-args) +* [F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms](#rf-reference-capture) +* [F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread](#rf-value-capture) +* [F.54: When writing a lambda that captures `this` or any class data member, don't use `[=]` default capture](#rf-this-capture) +* [F.55: Don't use `va_arg` arguments](#f-varargs) +* [F.56: Avoid unnecessary condition nesting](#f-nesting) Functions have strong similarities to lambdas and function objects. -**See also**: [C.lambdas: Function objects and lambdas](#SS-lambdas) +**See also**: [C.lambdas: Function objects and lambdas](#ss-lambdas) -## F.def: Function definitions +## F.def: Function definitions A function definition is a function declaration that also specifies the function's implementation, the function body. -### F.1: "Package" meaningful operations as carefully named functions +### F.1: "Package" meaningful operations as carefully named functions ##### Reason @@ -2443,15 +2443,15 @@ The shortest code is not always the best for performance or maintainability. Loop bodies, including lambdas used as loop bodies, rarely need to be named. However, large loop bodies (e.g., dozens of lines or dozens of pages) can be a problem. -The rule [Keep functions short and simple](#Rf-single) implies "Keep loop bodies short." +The rule [Keep functions short and simple](#rf-single) implies "Keep loop bodies short." Similarly, lambdas used as callback arguments are sometimes non-trivial, yet unlikely to be reusable. ##### Enforcement -* See [Keep functions short and simple](#Rf-single) +* See [Keep functions short and simple](#rf-single) * Flag identical and very similar lambdas used in different places. -### F.2: A function should perform a single logical operation +### F.2: A function should perform a single logical operation ##### Reason @@ -2511,7 +2511,7 @@ If there was a need, we could further templatize `read()` and `print()` on the d * Consider "large" functions that don't fit on one editor screen suspicious. Consider factoring such a function into smaller well-named suboperations. * Consider functions with 7 or more parameters suspicious. -### F.3: Keep functions short and simple +### F.3: Keep functions short and simple ##### Reason @@ -2595,7 +2595,7 @@ Small simple functions are easily inlined where the cost of a function call is s * Flag functions that are too complex. How complex is too complex? You could use cyclomatic complexity. Try "more than 10 logical paths through." Count a simple switch as one path. -### F.4: If a function might have to be evaluated at compile time, declare it `constexpr` +### F.4: If a function might have to be evaluated at compile time, declare it `constexpr` ##### Reason @@ -2649,7 +2649,7 @@ that API would have to be refactored or drop `constexpr`. Impossible and unnecessary. The compiler gives an error if a non-`constexpr` function is called where a constant is required. -### F.5: If a function is very small and time-critical, declare it `inline` +### F.5: If a function is very small and time-critical, declare it `inline` ##### Reason @@ -2683,7 +2683,7 @@ Function templates (including member functions of class templates `A::functio Consider making functions out of line if they are more than three statements and can be declared out of line (such as class member functions). -### F.6: If your function must not throw, declare it `noexcept` +### F.6: If your function must not throw, declare it `noexcept` ##### Reason @@ -2738,7 +2738,7 @@ low-level functions. ##### Note Destructors, `swap` functions, move operations, and default constructors should never throw. -See also [C.44](#Rc-default00). +See also [C.44](#rc-default00). ##### Note @@ -2749,7 +2749,7 @@ Care must be taken on base virtual functions and functions part of a public inte * (hard) Flag low-level functions that are not `noexcept`, yet cannot throw. * Flag throwing `swap`, `move`, destructors, and default constructors. -### F.7: For general use, take `T*` or `T&` arguments rather than smart pointers +### F.7: For general use, take `T*` or `T&` arguments rather than smart pointers ##### Reason @@ -2814,7 +2814,7 @@ Passing a shared smart pointer (e.g., `std::shared_ptr`) implies a run-time cost ##### Note -We can catch many common cases of dangling pointers statically (see [lifetime safety profile](#SS-lifetime)). Function arguments naturally live for the lifetime of the function call, and so have fewer lifetime problems. +We can catch many common cases of dangling pointers statically (see [lifetime safety profile](#ss-lifetime)). Function arguments naturally live for the lifetime of the function call, and so have fewer lifetime problems. ##### Enforcement @@ -2825,10 +2825,10 @@ We can catch many common cases of dangling pointers statically (see [lifetime sa **See also**: -* [Prefer `T*` over `T&` when "no argument" is a valid option](#Rf-ptr-ref) -* [Smart pointer rule summary](#Rr-summary-smartptrs) +* [Prefer `T*` over `T&` when "no argument" is a valid option](#rf-ptr-ref) +* [Smart pointer rule summary](#rr-summary-smartptrs) -### F.8: Prefer pure functions +### F.8: Prefer pure functions ##### Reason @@ -2843,7 +2843,7 @@ Pure functions are easier to reason about, sometimes easier to optimize (and eve Not possible. -### F.9: Unused parameters should be unnamed +### F.9: Unused parameters should be unnamed ##### Reason @@ -2874,7 +2874,7 @@ For example: Flag named unused parameters. -### F.10: If an operation can be reused, give it a name +### F.10: If an operation can be reused, give it a name ##### Reason @@ -2939,7 +2939,7 @@ whether functions, lambdas, or operators. * (hard) flag similar lambdas * ??? -### F.11: Use an unnamed lambda if you need a simple function object in one place only +### F.11: Use an unnamed lambda if you need a simple function object in one place only ##### Reason @@ -2959,11 +2959,11 @@ Naming a lambda can be useful for clarity even if it is used only once. * Look for identical and near identical lambdas (to be replaced with named functions or named lambdas). -## F.call: Parameter passing +## F.call: Parameter passing There are a variety of ways to pass parameters to a function and to return values. -### F.15: Prefer simple and conventional ways of passing information +### F.15: Prefer simple and conventional ways of passing information ##### Reason @@ -2982,14 +2982,14 @@ Advanced parameter passing: Use the advanced techniques only after demonstrating need, and document that need in a comment. -For passing sequences of characters see [String](#SS-string). +For passing sequences of characters see [String](#ss-string). ##### Exception To express shared ownership using `shared_ptr` types, rather than following guidelines F.16-21, -follow [R.34](#Rr-sharedptrparam-owner), [R.35](#Rr-sharedptrparam), and [R.36](#Rr-sharedptrparam-const). +follow [R.34](#rr-sharedptrparam-owner), [R.35](#rr-sharedptrparam), and [R.36](#rr-sharedptrparam-const). -### F.16: For "in" parameters, pass cheaply-copied types by value and others by reference to `const` +### F.16: For "in" parameters, pass cheaply-copied types by value and others by reference to `const` ##### Reason @@ -3010,11 +3010,11 @@ When copying is cheap, nothing beats the simplicity and safety of copying, and f For advanced uses (only), where you really need to optimize for rvalues passed to "input-only" parameters: -* If the function is going to unconditionally move from the argument, take it by `&&`. See [F.18](#Rf-consume). +* If the function is going to unconditionally move from the argument, take it by `&&`. See [F.18](#rf-consume). * If the function is going to keep a locally modifiable copy of the argument only for its own local use, taking it by value is fine. * If the function is going to keep a copy of the argument to pass to another destination (to another function, or store in a non-local location), in addition to passing by `const&` (for lvalues), - add an overload that passes the parameter by `&&` (for rvalues) and in the body `std::move`s it to its destination. Essentially this overloads a "will-move-from"; see [F.18](#Rf-consume). -* In special cases, such as multiple "input + copy" parameters, consider using perfect forwarding. See [F.19](#Rf-forward). + add an overload that passes the parameter by `&&` (for rvalues) and in the body `std::move`s it to its destination. Essentially this overloads a "will-move-from"; see [F.18](#rf-consume). +* In special cases, such as multiple "input + copy" parameters, consider using perfect forwarding. See [F.19](#rf-forward). ##### Example @@ -3026,7 +3026,7 @@ For advanced uses (only), where you really need to optimize for rvalues passed t void sink(unique_ptr); // input only, and moves ownership of the widget Avoid "esoteric techniques" such as passing arguments as `T&&` "for efficiency". -Most rumors about performance advantages from passing by `&&` are false or brittle (but see [F.18](#Rf-consume) and [F.19](#Rf-forward)). +Most rumors about performance advantages from passing by `&&` are false or brittle (but see [F.18](#rf-consume) and [F.19](#rf-forward)). ##### Notes @@ -3043,10 +3043,10 @@ If you need the notion of an optional value, use a pointer, `std::optional`, or ##### Exception -To express shared ownership using `shared_ptr` types, follow [R.34](#Rr-sharedptrparam-owner) or [R.36](#Rr-sharedptrparam-const), +To express shared ownership using `shared_ptr` types, follow [R.34](#rr-sharedptrparam-owner) or [R.36](#rr-sharedptrparam-const), depending on whether or not the function unconditionally takes a reference to the argument. -### F.17: For "in-out" parameters, pass by reference to non-`const` +### F.17: For "in-out" parameters, pass by reference to non-`const` ##### Reason @@ -3059,7 +3059,7 @@ This makes it clear to callers that the object is assumed to be modified. ##### Note Some user-defined and standard library types, such as `span` or the iterators -are [cheap to copy](#Rf-in) and may be passed by value, while doing so has +are [cheap to copy](#rf-in) and may be passed by value, while doing so has mutable (in-out) reference semantics: void increment_all(span a) @@ -3093,7 +3093,7 @@ A bad logic error can happen if the writer of `g()` incorrectly assumes the size * (Moderate) ((Foundation)) Warn about functions regarding reference to non-`const` parameters that do *not* write to them. * (Simple) ((Foundation)) Warn when a non-`const` parameter being passed by reference is `move`d. -### F.18: For "will-move-from" parameters, pass by `X&&` and `std::move` the parameter +### F.18: For "will-move-from" parameters, pass by `X&&` and `std::move` the parameter ##### Reason @@ -3109,7 +3109,7 @@ It's efficient and eliminates bugs at the call site: `X&&` binds to rvalues, whi } Note that the `std::move(v)` makes it possible for `store_somewhere()` to leave `v` in a moved-from state. -[That could be dangerous](#Rc-move-semantic). +[That could be dangerous](#rc-move-semantic). ##### Exception @@ -3126,7 +3126,7 @@ For example: ##### Exception -If the "will-move-from" parameter is a `shared_ptr` follow [R.34](#Rr-sharedptrparam-owner) and pass the `shared_ptr` by value. +If the "will-move-from" parameter is a `shared_ptr` follow [R.34](#rr-sharedptrparam-owner) and pass the `shared_ptr` by value. ##### Enforcement @@ -3134,7 +3134,7 @@ If the "will-move-from" parameter is a `shared_ptr` follow [R.34](#Rr-sharedptrp * Flag access to moved-from objects. * Don't conditionally move from objects -### F.19: For "forward" parameters, pass by `TP&&` and only `std::forward` the parameter +### F.19: For "forward" parameters, pass by `TP&&` and only `std::forward` the parameter ##### Reason @@ -3168,7 +3168,7 @@ Sometimes you may forward a composite parameter piecewise, each subobject once o * Flag a function that takes a `TP&&` parameter (where `TP` is a template type parameter name) and does anything with it other than `std::forward`ing it exactly once on every static path, or `std::forward`ing it more than once but qualified with a different data member exactly once on every static path. -### F.20: For "out" output values, prefer return values to output parameters +### F.20: For "out" output values, prefer return values to output parameters ##### Reason @@ -3176,7 +3176,7 @@ A return value is self-documenting, whereas an `&` could be either in-out or out This includes large objects like standard containers that use implicit move operations for performance and to avoid explicit memory management. -If you have multiple values to return, [use a tuple](#Rf-out-multi) or similar multi-member type. +If you have multiple values to return, [use a tuple](#rf-out-multi) or similar multi-member type. ##### Example @@ -3194,7 +3194,7 @@ A `struct` of many (individually cheap-to-move) elements might be in aggregate e * For non-concrete types, such as types in an inheritance hierarchy, return the object by `unique_ptr` or `shared_ptr`. * If a type is expensive to move (e.g., `array`), consider allocating it on the free store and return a handle (e.g., `unique_ptr`), or passing it in a reference to non-`const` target object to fill (to be used as an out-parameter). -* To reuse an object that carries capacity (e.g., `std::string`, `std::vector`) across multiple calls to the function in an inner loop: [treat it as an in/out parameter and pass by reference](#Rf-out-multi). +* To reuse an object that carries capacity (e.g., `std::string`, `std::vector`) across multiple calls to the function in an inner loop: [treat it as an in/out parameter and pass by reference](#rf-out-multi). ##### Example @@ -3233,7 +3233,7 @@ The return value optimization doesn't handle the assignment case, but the move a * Flag reference to non-`const` parameters that are not read before being written to and are a type that could be cheaply returned; they should be "out" return values. -### F.21: To return multiple "out" values, prefer returning a struct +### F.21: To return multiple "out" values, prefer returning a struct ##### Reason @@ -3281,7 +3281,7 @@ See for example `ranges::min_max_result`, `from_chars_result`, and others. ##### Exception Sometimes, we need to pass an object to a function to manipulate its state. -In such cases, passing the object by reference [`T&`](#Rf-inout) is usually the right technique. +In such cases, passing the object by reference [`T&`](#rf-inout) is usually the right technique. Explicitly passing an in-out parameter back out again as a return value is often not necessary. For example: @@ -3361,7 +3361,7 @@ Alternatively, return { g(input), h(input) }; // no copies, no moves } -Note this is different from the `return move(...)` anti-pattern from [ES.56](#Res-move). +Note this is different from the `return move(...)` anti-pattern from [ES.56](#res-move). ##### Enforcement @@ -3370,7 +3370,7 @@ Note this is different from the `return move(...)` anti-pattern from [ES.56](#Re * `pair` or `tuple` return types should be replaced by `struct`, if possible. In variadic templates, `tuple` is often unavoidable. -### F.60: Prefer `T*` over `T&` when "no argument" is a valid option +### F.60: Prefer `T*` over `T&` when "no argument" is a valid option ##### Reason @@ -3403,7 +3403,7 @@ If you prefer the pointer notation (`->` and/or `*` vs. `.`), `not_null` pro * Flag ??? -### F.22: Use `T*` or `owner` to designate a single object +### F.22: Use `T*` or `owner` to designate a single object ##### Reason @@ -3453,13 +3453,13 @@ better **See also**: [Support library](#gsl-guidelines-support-library) -**See also**: [Do not pass an array as a single pointer](#Ri-array) +**See also**: [Do not pass an array as a single pointer](#ri-array) ##### Enforcement * (Simple) ((Bounds)) Warn for any arithmetic operation on an expression of pointer type that results in a value of pointer type. -### F.23: Use a `not_null` to indicate that "null" is not a valid value +### F.23: Use a `not_null` to indicate that "null" is not a valid value ##### Reason @@ -3497,7 +3497,7 @@ A `not_null` is assumed not to be the `nullptr`; a `T*` might be the `nullpt * (Simple) Error if a raw pointer is sometimes dereferenced after first being tested against `nullptr` (or equivalent) within the function and sometimes is not. * (Simple) Warn if a `not_null` pointer is tested against `nullptr` within a function. -### F.24: Use a `span` or a `span_p` to designate a half-open sequence +### F.24: Use a `span` or a `span_p` to designate a half-open sequence ##### Reason @@ -3549,7 +3549,7 @@ Passing a `span` object as an argument is exactly as efficient as passing a pair (Complex) Warn where accesses to pointer parameters are bounded by other parameters that are integral types and suggest they could use `span` instead. -### F.25: Use a `zstring` or a `not_null` to designate a C-style string +### F.25: Use a `zstring` or a `not_null` to designate a C-style string ##### Reason @@ -3578,13 +3578,13 @@ When I call `length(s)` should I check if `s` is `nullptr` first? Should the imp **See also**: [Support library](#gsl-guidelines-support-library) -### F.26: Use a `unique_ptr` to transfer ownership where a pointer is needed +### F.26: Use a `unique_ptr` to transfer ownership where a pointer is needed ##### Reason Using `unique_ptr` is the cheapest way to pass a pointer safely. -**See also**: [C.50](#Rc-factory) regarding when to return a `shared_ptr` from a factory. +**See also**: [C.50](#rc-factory) regarding when to return a `shared_ptr` from a factory. ##### Example @@ -3608,7 +3608,7 @@ You need to pass a pointer rather than an object if what you are transferring is (Simple) Warn if a function returns a locally allocated raw pointer. Suggest using either `unique_ptr` or `shared_ptr` instead. -### F.27: Use a `shared_ptr` to share ownership +### F.27: Use a `shared_ptr` to share ownership ##### Reason @@ -3645,7 +3645,7 @@ Have a single object own the shared object (e.g. a scoped object) and destroy th (Not enforceable) This is a too complex pattern to reliably detect. -### F.42: Return a `T*` to indicate a position (only) +### F.42: Return a `T*` to indicate a position (only) ##### Reason @@ -3668,11 +3668,11 @@ Importantly, that does not imply a transfer of ownership of the pointed-to objec ##### Note Positions can also be transferred by iterators, indices, and references. -A reference is often a superior alternative to a pointer [if there is no need to use `nullptr`](#Rf-ptr-ref) or [if the object referred to should not change](#S-const). +A reference is often a superior alternative to a pointer [if there is no need to use `nullptr`](#rf-ptr-ref) or [if the object referred to should not change](#s-const). ##### Note -Do not return a pointer to something that is not in the caller's scope; see [F.43](#Rf-dangle). +Do not return a pointer to something that is not in the caller's scope; see [F.43](#rf-dangle). **See also**: [discussion of dangling pointer prevention](#???) @@ -3683,7 +3683,7 @@ Only owners should be deleted. * Flag `new`, `malloc()`, etc. assigned to a plain `T*`. Only owners should be responsible for deletion. -### F.43: Never (directly or indirectly) return a pointer or a reference to a local object +### F.43: Never (directly or indirectly) return a pointer or a reference to a local object ##### Reason @@ -3790,7 +3790,7 @@ It can be detected/prevented with similar techniques. * Compilers tend to catch return of reference to locals and could in many cases catch return of pointers to locals. * Static analysis can catch many common patterns of the use of pointers indicating positions (thus eliminating dangling pointers) -### F.44: Return a `T&` when copy is undesirable and "returning no object" isn't needed +### F.44: Return a `T&` when copy is undesirable and "returning no object" isn't needed ##### Reason @@ -3820,7 +3820,7 @@ The language guarantees that a `T&` refers to an object, so that testing for `nu Flag functions where no `return` expression could yield `nullptr`. -### F.45: Don't return a `T&&` +### F.45: Don't return a `T&&` ##### Reason @@ -3837,13 +3837,13 @@ A returned rvalue reference goes out of scope at the end of the full expression This kind of use is a frequent source of bugs, often incorrectly reported as a compiler bug. An implementer of a function should avoid setting such traps for users. -The [lifetime safety profile](#SS-lifetime) will (when completely implemented) catch such problems. +The [lifetime safety profile](#ss-lifetime) will (when completely implemented) catch such problems. ##### Example Returning an rvalue reference is fine when the reference to the temporary is being passed "downward" to a callee; -then, the temporary is guaranteed to outlive the function call (see [F.18](#Rf-consume) and [F.19](#Rf-forward)). +then, the temporary is guaranteed to outlive the function call (see [F.18](#rf-consume) and [F.19](#rf-forward)). However, it's not fine when passing such a reference "upward" to a larger caller scope. For passthrough functions that pass in parameters (by ordinary reference or by perfect forwarding) and want to return values, use simple `auto` return type deduction (not `auto&&`). @@ -3874,7 +3874,7 @@ Better: Flag any use of `&&` as a return type, except in `std::move` and `std::forward`. -### F.46: `int` is the return type for `main()` +### F.46: `int` is the return type for `main()` ##### Reason @@ -3900,7 +3900,7 @@ Note that despite its non-void return type, the main function does not require a * The compiler should do it * If the compiler doesn't do it, let tools flag it -### F.47: Return `T&` from assignment operators +### F.47: Return `T&` from assignment operators ##### Reason @@ -3933,7 +3933,7 @@ This was primarily to avoid code of the form `(a = b) = c` -- such code is not c This should be enforced by tooling by checking the return type (and return value) of any assignment operator. -### F.48: Don't `return std::move(local)` +### F.48: Don't `return std::move(local)` ##### Reason @@ -3962,7 +3962,7 @@ which can eliminate the move completely. This should be enforced by tooling by checking the return expression. -### F.49: Don't return `const T` +### F.49: Don't return `const T` ##### Reason @@ -3985,14 +3985,14 @@ Such older advice is now obsolete; it does not add value, and it interferes with The argument for adding `const` to a return value is that it prevents (very rare) accidental access to a temporary. The argument against is that it prevents (very frequent) use of move semantics. -**See also**: [F.20, the general item about "out" output values](#Rf-out) +**See also**: [F.20, the general item about "out" output values](#rf-out) ##### Enforcement * Flag returning a `const` value. To fix: Remove `const` to return a non-`const` value instead. -### F.50: Use a lambda when a function won't do (to capture local variables, or to write a local function) +### F.50: Use a lambda when a function won't do (to capture local variables, or to write a local function) ##### Reason @@ -4027,7 +4027,7 @@ Generic lambdas offer a concise way to write function templates and so can be us * Warn on use of a named non-generic lambda (e.g., `auto x = [](int i) { /*...*/; };`) that captures nothing and appears at global scope. Write an ordinary function instead. -### F.51: Where there is a choice, prefer default arguments over overloading +### F.51: Where there is a choice, prefer default arguments over overloading ##### Reason @@ -4056,13 +4056,13 @@ There is not a choice when a set of functions are used to do a semantically equi ##### See also -[Default arguments for virtual functions](#Rh-virtual-default-arg) +[Default arguments for virtual functions](#rh-virtual-default-arg) ##### Enforcement * Warn on an overload set where the overloads have a common prefix of parameters (e.g., `f(int)`, `f(int, const string&)`, `f(int, const string&, double)`). (Note: Review this enforcement if it's too noisy in practice.) -### F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms +### F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms ##### Reason @@ -4103,7 +4103,7 @@ This is a simple three-stage parallel pipeline. Each `stage` object encapsulates Flag a lambda that captures by reference, but is used other than locally within the function scope or passed to a function by reference. (Note: This rule is an approximation, but does flag passing by pointer as those are more likely to be stored by the callee, writing to a heap location accessed via a parameter, returning the lambda, etc. The Lifetime rules will also provide general rules that flag escaping pointers and references including via lambdas.) -### F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread +### F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread ##### Reason @@ -4138,7 +4138,7 @@ If the `this` pointer must be captured, consider using `[*this]` capture, which * (Simple) Warn when capture-list contains a reference to a locally declared variable * (Complex) Flag when capture-list contains a reference to a locally declared variable and the lambda is passed to a non-`const` and non-local context -### F.54: When writing a lambda that captures `this` or any class data member, don't use `[=]` default capture +### F.54: When writing a lambda that captures `this` or any class data member, don't use `[=]` default capture ##### Reason @@ -4178,7 +4178,7 @@ If you intend to capture a copy of all class data members, consider C++17 `[*thi * Flag any lambda capture-list that specifies a capture-default of `[=]` and also captures `this` (whether explicitly or via the default capture and a use of `this` in the body) -### F.55: Don't use `va_arg` arguments +### F.55: Don't use `va_arg` arguments ##### Reason @@ -4225,7 +4225,7 @@ Declaring a `...` parameter is sometimes useful for techniques that don't involv * Issue a diagnostic for passing an argument to a vararg parameter of a function that does not offer an overload for a more specific type in the position of the vararg. To fix: Use a different function, or `[[suppress("type")]]`. -### F.56: Avoid unnecessary condition nesting +### F.56: Avoid unnecessary condition nesting ##### Reason @@ -4291,33 +4291,33 @@ Flag a redundant `else`. Flag a function whose body is simply a conditional statement enclosing a block. -# C: Classes and class hierarchies +# C: Classes and class hierarchies A class is a user-defined type, for which a programmer can define the representation, operations, and interfaces. Class hierarchies are used to organize related classes into hierarchical structures. Class rule summary: -* [C.1: Organize related data into structures (`struct`s or `class`es)](#Rc-org) -* [C.2: Use `class` if the class has an invariant; use `struct` if the data members can vary independently](#Rc-struct) -* [C.3: Represent the distinction between an interface and an implementation using a class](#Rc-interface) -* [C.4: Make a function a member only if it needs direct access to the representation of a class](#Rc-member) -* [C.5: Place helper functions in the same namespace as the class they support](#Rc-helper) -* [C.7: Don't define a class or enum and declare a variable of its type in the same statement](#Rc-standalone) -* [C.8: Use `class` rather than `struct` if any member is non-public](#Rc-class) -* [C.9: Minimize exposure of members](#Rc-private) +* [C.1: Organize related data into structures (`struct`s or `class`es)](#rc-org) +* [C.2: Use `class` if the class has an invariant; use `struct` if the data members can vary independently](#rc-struct) +* [C.3: Represent the distinction between an interface and an implementation using a class](#rc-interface) +* [C.4: Make a function a member only if it needs direct access to the representation of a class](#rc-member) +* [C.5: Place helper functions in the same namespace as the class they support](#rc-helper) +* [C.7: Don't define a class or enum and declare a variable of its type in the same statement](#rc-standalone) +* [C.8: Use `class` rather than `struct` if any member is non-public](#rc-class) +* [C.9: Minimize exposure of members](#rc-private) Subsections: -* [C.concrete: Concrete types](#SS-concrete) -* [C.ctor: Constructors, assignments, and destructors](#S-ctor) -* [C.con: Containers and other resource handles](#SS-containers) -* [C.lambdas: Function objects and lambdas](#SS-lambdas) -* [C.hier: Class hierarchies (OOP)](#SS-hier) -* [C.over: Overloading and overloaded operators](#SS-overload) -* [C.union: Unions](#SS-union) +* [C.concrete: Concrete types](#ss-concrete) +* [C.ctor: Constructors, assignments, and destructors](#s-ctor) +* [C.con: Containers and other resource handles](#ss-containers) +* [C.lambdas: Function objects and lambdas](#ss-lambdas) +* [C.hier: Class hierarchies (OOP)](#ss-hier) +* [C.over: Overloading and overloaded operators](#ss-overload) +* [C.union: Unions](#ss-union) -### C.1: Organize related data into structures (`struct`s or `class`es) +### C.1: Organize related data into structures (`struct`s or `class`es) ##### Reason @@ -4341,7 +4341,7 @@ From a language perspective `class` and `struct` differ only in the default visi Probably impossible. Maybe a heuristic looking for data items used together is possible. -### C.2: Use `class` if the class has an invariant; use `struct` if the data members can vary independently +### C.2: Use `class` if the class has an invariant; use `struct` if the data members can vary independently ##### Reason @@ -4386,16 +4386,16 @@ This effectively means the definer needs to define an invariant. **See also**: -* [define a class with private data as `class`](#Rc-class) -* [Prefer to place the interface first in a class](#Rl-order) -* [minimize exposure of members](#Rc-private) -* [Avoid `protected` data](#Rh-protected) +* [define a class with private data as `class`](#rc-class) +* [Prefer to place the interface first in a class](#rl-order) +* [minimize exposure of members](#rc-private) +* [Avoid `protected` data](#rh-protected) ##### Enforcement Look for `struct`s with all data private and `class`es with public members. -### C.3: Represent the distinction between an interface and an implementation using a class +### C.3: Represent the distinction between an interface and an implementation using a class ##### Reason @@ -4429,7 +4429,7 @@ Ideally, and typically, an interface is far more stable than its implementation( ??? -### C.4: Make a function a member only if it needs direct access to the representation of a class +### C.4: Make a function a member only if it needs direct access to the representation of a class ##### Reason @@ -4491,7 +4491,7 @@ The snag is that many member functions that do not need to touch data members di * Ignore functions that are part of an overload set out of which at least one function accesses `private` members. * Ignore functions returning `this`. -### C.5: Place helper functions in the same namespace as the class they support +### C.5: Place helper functions in the same namespace as the class they support ##### Reason @@ -4513,13 +4513,13 @@ Placing them in the same namespace as the class makes their relationship to the ##### Note -This is especially important for [overloaded operators](#Ro-namespace). +This is especially important for [overloaded operators](#ro-namespace). ##### Enforcement * Flag global functions taking argument types from a single namespace. -### C.7: Don't define a class or enum and declare a variable of its type in the same statement +### C.7: Don't define a class or enum and declare a variable of its type in the same statement ##### Reason @@ -4538,7 +4538,7 @@ Mixing a type definition and the definition of another entity in the same declar * Flag if the `}` of a class or enumeration definition is not followed by a `;`. The `;` is missing. -### C.8: Use `class` rather than `struct` if any member is non-public +### C.8: Use `class` rather than `struct` if any member is non-public ##### Reason @@ -4566,13 +4566,13 @@ All of this decreases readability and complicates maintenance. ##### Note -Prefer to place the interface first in a class, [see NL.16](#Rl-order). +Prefer to place the interface first in a class, [see NL.16](#rl-order). ##### Enforcement Flag classes declared with `struct` if there is a `private` or `protected` member. -### C.9: Minimize exposure of members +### C.9: Minimize exposure of members ##### Reason @@ -4652,27 +4652,27 @@ For example, a derived class might be allowed to skip a run-time check because i ##### Note -[`protected` data is a bad idea](#Rh-protected). +[`protected` data is a bad idea](#rh-protected). ##### Note -Prefer the order `public` members before `protected` members before `private` members; see [NL.16](#Rl-order). +Prefer the order `public` members before `protected` members before `private` members; see [NL.16](#rl-order). ##### Enforcement -* [Flag protected data](#Rh-protected). +* [Flag protected data](#rh-protected). * Flag mixtures of `public` and `private` data -## C.concrete: Concrete types +## C.concrete: Concrete types Concrete type rule summary: -* [C.10: Prefer concrete types over class hierarchies](#Rc-concrete) -* [C.11: Make concrete types regular](#Rc-regular) -* [C.12: Don't make data members `const` or references in a copyable or movable type](#Rc-constref) +* [C.10: Prefer concrete types over class hierarchies](#rc-concrete) +* [C.11: Make concrete types regular](#rc-regular) +* [C.12: Don't make data members `const` or references in a copyable or movable type](#rc-constref) -### C.10: Prefer concrete types over class hierarchies +### C.10: Prefer concrete types over class hierarchies ##### Reason @@ -4724,7 +4724,7 @@ This is done where dynamic allocation is prohibited (e.g. hard-real-time) and to ??? -### C.11: Make concrete types regular +### C.11: Make concrete types regular ##### Reason @@ -4766,7 +4766,7 @@ so they can't be regular; instead, they tend to be move-only. ??? -### C.12: Don't make data members `const` or references in a copyable or movable type +### C.12: Don't make data members `const` or references in a copyable or movable type ##### Reason @@ -4792,7 +4792,7 @@ Flag a data member that is `const`, `&`, or `&&` in a type that has any copy or -## C.ctor: Constructors, assignments, and destructors +## C.ctor: Constructors, assignments, and destructors These functions control the lifecycle of objects: creation, copy, move, and destruction. Define constructors to guarantee and simplify initialization of classes. @@ -4813,66 +4813,66 @@ By default, C++ treats classes as value-like types, but not all types are value- Set of default operations rules: -* [C.20: If you can avoid defining any default operations, do](#Rc-zero) -* [C.21: If you define or `=delete` any copy, move, or destructor function, define or `=delete` them all](#Rc-five) -* [C.22: Make default operations consistent](#Rc-matched) +* [C.20: If you can avoid defining any default operations, do](#rc-zero) +* [C.21: If you define or `=delete` any copy, move, or destructor function, define or `=delete` them all](#rc-five) +* [C.22: Make default operations consistent](#rc-matched) Destructor rules: -* [C.30: Define a destructor if a class needs an explicit action at object destruction](#Rc-dtor) -* [C.31: All resources acquired by a class must be released by the class's destructor](#Rc-dtor-release) -* [C.32: If a class has a raw pointer (`T*`) or reference (`T&`), consider whether it might be owning](#Rc-dtor-ptr) -* [C.33: If a class has an owning pointer member, define a destructor](#Rc-dtor-ptr2) -* [C.35: A base class destructor should be either public and virtual, or protected and non-virtual](#Rc-dtor-virtual) -* [C.36: A destructor must not fail](#Rc-dtor-fail) -* [C.37: Make destructors `noexcept`](#Rc-dtor-noexcept) +* [C.30: Define a destructor if a class needs an explicit action at object destruction](#rc-dtor) +* [C.31: All resources acquired by a class must be released by the class's destructor](#rc-dtor-release) +* [C.32: If a class has a raw pointer (`T*`) or reference (`T&`), consider whether it might be owning](#rc-dtor-ptr) +* [C.33: If a class has an owning pointer member, define a destructor](#rc-dtor-ptr2) +* [C.35: A base class destructor should be either public and virtual, or protected and non-virtual](#rc-dtor-virtual) +* [C.36: A destructor must not fail](#rc-dtor-fail) +* [C.37: Make destructors `noexcept`](#rc-dtor-noexcept) Constructor rules: -* [C.40: Define a constructor if a class has an invariant](#Rc-ctor) -* [C.41: A constructor should create a fully initialized object](#Rc-complete) -* [C.42: If a constructor cannot construct a valid object, throw an exception](#Rc-throw) -* [C.43: Ensure that a copyable class has a default constructor](#Rc-default0) -* [C.44: Prefer default constructors to be simple and non-throwing](#Rc-default00) -* [C.45: Don't define a default constructor that only initializes data members; use member initializers instead](#Rc-default) -* [C.46: By default, declare single-argument constructors `explicit`](#Rc-explicit) -* [C.47: Define and initialize data members in the order of member declaration](#Rc-order) -* [C.48: Prefer default member initializers to member initializers in constructors for constant initializers](#Rc-in-class-initializer) -* [C.49: Prefer initialization to assignment in constructors](#Rc-initialize) -* [C.50: Use a factory function if you need "virtual behavior" during initialization](#Rc-factory) -* [C.51: Use delegating constructors to represent common actions for all constructors of a class](#Rc-delegating) -* [C.52: Use inheriting constructors to import constructors into a derived class that does not need further explicit initialization](#Rc-inheriting) +* [C.40: Define a constructor if a class has an invariant](#rc-ctor) +* [C.41: A constructor should create a fully initialized object](#rc-complete) +* [C.42: If a constructor cannot construct a valid object, throw an exception](#rc-throw) +* [C.43: Ensure that a copyable class has a default constructor](#rc-default0) +* [C.44: Prefer default constructors to be simple and non-throwing](#rc-default00) +* [C.45: Don't define a default constructor that only initializes data members; use member initializers instead](#rc-default) +* [C.46: By default, declare single-argument constructors `explicit`](#rc-explicit) +* [C.47: Define and initialize data members in the order of member declaration](#rc-order) +* [C.48: Prefer default member initializers to member initializers in constructors for constant initializers](#rc-in-class-initializer) +* [C.49: Prefer initialization to assignment in constructors](#rc-initialize) +* [C.50: Use a factory function if you need "virtual behavior" during initialization](#rc-factory) +* [C.51: Use delegating constructors to represent common actions for all constructors of a class](#rc-delegating) +* [C.52: Use inheriting constructors to import constructors into a derived class that does not need further explicit initialization](#rc-inheriting) Copy and move rules: -* [C.60: Make copy assignment non-`virtual`, take the parameter by `const&`, and return by non-`const&`](#Rc-copy-assignment) -* [C.61: A copy operation should copy](#Rc-copy-semantic) -* [C.62: Make copy assignment safe for self-assignment](#Rc-copy-self) -* [C.63: Make move assignment non-`virtual`, take the parameter by `&&`, and return by non-`const&`](#Rc-move-assignment) -* [C.64: A move operation should move and leave its source in a valid state](#Rc-move-semantic) -* [C.65: Make move assignment safe for self-assignment](#Rc-move-self) -* [C.66: Make move operations `noexcept`](#Rc-move-noexcept) -* [C.67: A polymorphic class should suppress public copy/move](#Rc-copy-virtual) +* [C.60: Make copy assignment non-`virtual`, take the parameter by `const&`, and return by non-`const&`](#rc-copy-assignment) +* [C.61: A copy operation should copy](#rc-copy-semantic) +* [C.62: Make copy assignment safe for self-assignment](#rc-copy-self) +* [C.63: Make move assignment non-`virtual`, take the parameter by `&&`, and return by non-`const&`](#rc-move-assignment) +* [C.64: A move operation should move and leave its source in a valid state](#rc-move-semantic) +* [C.65: Make move assignment safe for self-assignment](#rc-move-self) +* [C.66: Make move operations `noexcept`](#rc-move-noexcept) +* [C.67: A polymorphic class should suppress public copy/move](#rc-copy-virtual) Other default operations rules: -* [C.80: Use `=default` if you have to be explicit about using the default semantics](#Rc-eqdefault) -* [C.81: Use `=delete` when you want to disable default behavior (without wanting an alternative)](#Rc-delete) -* [C.82: Don't call virtual functions in constructors and destructors](#Rc-ctor-virtual) -* [C.83: For value-like types, consider providing a `noexcept` swap function](#Rc-swap) -* [C.84: A `swap` must not fail](#Rc-swap-fail) -* [C.85: Make `swap` `noexcept`](#Rc-swap-noexcept) -* [C.86: Make `==` symmetric with respect of operand types and `noexcept`](#Rc-eq) -* [C.87: Beware of `==` on base classes](#Rc-eq-base) -* [C.89: Make a `hash` `noexcept`](#Rc-hash) -* [C.90: Rely on constructors and assignment operators, not memset and memcpy](#Rc-memset) +* [C.80: Use `=default` if you have to be explicit about using the default semantics](#rc-eqdefault) +* [C.81: Use `=delete` when you want to disable default behavior (without wanting an alternative)](#rc-delete) +* [C.82: Don't call virtual functions in constructors and destructors](#rc-ctor-virtual) +* [C.83: For value-like types, consider providing a `noexcept` swap function](#rc-swap) +* [C.84: A `swap` must not fail](#rc-swap-fail) +* [C.85: Make `swap` `noexcept`](#rc-swap-noexcept) +* [C.86: Make `==` symmetric with respect of operand types and `noexcept`](#rc-eq) +* [C.87: Beware of `==` on base classes](#rc-eq-base) +* [C.89: Make a `hash` `noexcept`](#rc-hash) +* [C.90: Rely on constructors and assignment operators, not memset and memcpy](#rc-memset) -## C.defop: Default Operations +## C.defop: Default Operations By default, the language supplies the default operations with their default semantics. However, a programmer can disable or replace these defaults. -### C.20: If you can avoid defining default operations, do +### C.20: If you can avoid defining default operations, do ##### Reason @@ -4905,7 +4905,7 @@ This is known as "the rule of zero". (Not enforceable) While not enforceable, a good static analyzer can detect patterns that indicate a possible improvement to meet this rule. For example, a class with a (pointer, size) pair of members and a destructor that `delete`s the pointer could probably be converted to a `vector`. -### C.21: If you define or `=delete` any copy, move, or destructor function, define or `=delete` them all +### C.21: If you define or `=delete` any copy, move, or destructor function, define or `=delete` them all ##### Reason @@ -4964,7 +4964,7 @@ defined as defaulted. // ... }; -To prevent slicing as per [C.67](#Rc-copy-virtual), +To prevent slicing as per [C.67](#rc-copy-virtual), make the copy and move operations protected or `=delete`d, and add a `clone`: class CloneableBase { @@ -5007,13 +5007,13 @@ Note their argument types: }; A minor mistake (such as a misspelling, leaving out a `const`, using `&` instead of `&&`, or leaving out a special function) can lead to errors or warnings. -To avoid the tedium and the possibility of errors, try to follow the [rule of zero](#Rc-zero). +To avoid the tedium and the possibility of errors, try to follow the [rule of zero](#rc-zero). ##### Enforcement (Simple) A class should have a declaration (even a `=delete` one) for either all or none of the copy/move/destructor functions. -### C.22: Make default operations consistent +### C.22: Make default operations consistent ##### Reason @@ -5042,14 +5042,14 @@ These operations disagree about copy semantics. This will lead to confusion and * (Complex) If a copy/move constructor performs a deep copy of a data member, then the destructor should modify the data member. * (Complex) If a destructor is modifying a data member, that data member should be written in any copy/move constructors or assignment operators. -## C.dtor: Destructors +## C.dtor: Destructors "Does this class need a destructor?" is a surprisingly insightful design question. -For most classes the answer is "no" either because the class holds no resources or because destruction is handled by [the rule of zero](#Rc-zero); +For most classes the answer is "no" either because the class holds no resources or because destruction is handled by [the rule of zero](#rc-zero); that is, its members can take care of themselves as concerns destruction. -If the answer is "yes", much of the design of the class follows (see [the rule of five](#Rc-five)). +If the answer is "yes", much of the design of the class follows (see [the rule of five](#rc-five)). -### C.30: Define a destructor if a class needs an explicit action at object destruction +### C.30: Define a destructor if a class needs an explicit action at object destruction ##### Reason @@ -5107,7 +5107,7 @@ The default destructor does it better, more efficiently, and can't get it wrong. Look for likely "implicit resources", such as pointers and references. Look for classes with destructors even though all their data members have destructors. -### C.31: All resources acquired by a class must be released by the class's destructor +### C.31: All resources acquired by a class must be released by the class's destructor ##### Reason @@ -5137,10 +5137,10 @@ For resources represented as classes with a complete set of default operations, ##### Note -What about a socket that won't close? A destructor, close, or cleanup operation [should never fail](#Rc-dtor-fail). +What about a socket that won't close? A destructor, close, or cleanup operation [should never fail](#rc-dtor-fail). If it does nevertheless, we have a problem that has no really good solution. For starters, the writer of a destructor does not know why the destructor is called and cannot "refuse to act" by throwing an exception. -See [discussion](#Sd-never-fail). +See [discussion](#sd-never-fail). To make the problem worse, many "close/release" operations are not retryable. Many have tried to solve this problem, but no general solution is known. If at all possible, consider failure to close/clean up a fundamental design error and terminate. @@ -5164,7 +5164,7 @@ Here `p` refers to `pp` but does not own it. * (Hard) Determine if pointer or reference members are owners when there is no explicit statement of ownership (e.g., look into the constructors). -### C.32: If a class has a raw pointer (`T*`) or reference (`T&`), consider whether it might be owning +### C.32: If a class has a raw pointer (`T*`) or reference (`T&`), consider whether it might be owning ##### Reason @@ -5182,14 +5182,14 @@ The only way to determine ownership may be code analysis. ##### Note -Ownership should be clear in new code (and refactored legacy code) according to [R.20](#Rr-owner) for owning -pointers and [R.3](#Rr-ptr) for non-owning pointers. References should never own [R.4](#Rr-ref). +Ownership should be clear in new code (and refactored legacy code) according to [R.20](#rr-owner) for owning +pointers and [R.3](#rr-ptr) for non-owning pointers. References should never own [R.4](#rr-ref). ##### Enforcement Look at the initialization of raw member pointers and member references and see if an allocation is used. -### C.33: If a class has an owning pointer member, define a destructor +### C.33: If a class has an owning pointer member, define a destructor ##### Reason @@ -5198,7 +5198,7 @@ An owned object must be `delete`d upon destruction of the object that owns it. ##### Example A pointer member could represent a resource. -[A `T*` should not do so](#Rr-ptr), but in older code, that's common. +[A `T*` should not do so](#rr-ptr), but in older code, that's common. Consider a `T*` a possible owner and therefore suspect. template @@ -5215,7 +5215,7 @@ Consider a `T*` a possible owner and therefore suspect. auto p2 = p1; } -Note that if you define a destructor, you must define or delete [all default operations](#Rc-five): +Note that if you define a destructor, you must define or delete [all default operations](#rc-five): template class Smart_ptr2 { @@ -5263,7 +5263,7 @@ That would sometimes require non-trivial code changes and might affect ABIs. * A class with an `owner` should define its default operations. -### C.35: A base class destructor should be either public and virtual, or protected and non-virtual +### C.35: A base class destructor should be either public and virtual, or protected and non-virtual ##### Reason @@ -5274,7 +5274,7 @@ In general, the writer of a base class does not know the appropriate action to b ##### Discussion -See [this in the Discussion section](#Sd-dtor). +See [this in the Discussion section](#sd-dtor). ##### Example, bad @@ -5324,7 +5324,7 @@ We can imagine one case where you could want a protected virtual destructor: Whe * A class with any virtual functions should have a destructor that is either public and virtual or else protected and non-virtual. * If a class inherits publicly from a base class, the base class should have a destructor that is either public and virtual or else protected and non-virtual. -### C.36: A destructor must not fail +### C.36: A destructor must not fail ##### Reason @@ -5352,7 +5352,7 @@ Many have tried to devise a fool-proof scheme for dealing with failure in destru None have succeeded to come up with a general scheme. This can be a real practical problem: For example, what about a socket that won't close? The writer of a destructor does not know why the destructor is called and cannot "refuse to act" by throwing an exception. -See [discussion](#Sd-never-fail). +See [discussion](#sd-never-fail). To make the problem worse, many "close/release" operations are not retryable. If at all possible, consider failure to close/clean up a fundamental design error and terminate. @@ -5378,11 +5378,11 @@ If a destructor uses operations that could fail, it can catch exceptions and in (Simple) A destructor should be declared `noexcept` if it could throw. -### C.37: Make destructors `noexcept` +### C.37: Make destructors `noexcept` ##### Reason - [A destructor must not fail](#Rc-dtor-fail). If a destructor tries to exit with an exception, it's a bad design error and the program had better terminate. + [A destructor must not fail](#rc-dtor-fail). If a destructor tries to exit with an exception, it's a bad design error and the program had better terminate. ##### Note @@ -5409,11 +5409,11 @@ Because that would in many cases -- especially simple cases -- be distracting cl (Simple) A destructor should be declared `noexcept` if it could throw. -## C.ctor: Constructors +## C.ctor: Constructors A constructor defines how an object is initialized (constructed). -### C.40: Define a constructor if a class has an invariant +### C.40: Define a constructor if a class has an invariant ##### Reason @@ -5463,15 +5463,15 @@ The C++11 initializer list rule eliminates the need for many constructors. For e Rec2 r2 {"Bar"}; The `Rec2` constructor is redundant. -Also, the default for `int` would be better done as a [default member initializer](#Rc-in-class-initializer). +Also, the default for `int` would be better done as a [default member initializer](#rc-in-class-initializer). -**See also**: [construct valid object](#Rc-complete) and [constructor throws](#Rc-throw). +**See also**: [construct valid object](#rc-complete) and [constructor throws](#rc-throw). ##### Enforcement * Flag classes with user-defined copy operations but no constructor (a user-defined copy is a good indicator that the class has an invariant) -### C.41: A constructor should create a fully initialized object +### C.41: A constructor should create a fully initialized object ##### Reason @@ -5502,7 +5502,7 @@ Compilers do not read comments. ##### Exception -If a valid object cannot conveniently be constructed by a constructor, [use a factory function](#Rc-factory). +If a valid object cannot conveniently be constructed by a constructor, [use a factory function](#rc-factory). ##### Enforcement @@ -5511,10 +5511,10 @@ If a valid object cannot conveniently be constructed by a constructor, [use a fa ##### Note -If a constructor acquires a resource (to create a valid object), that resource should be [released by the destructor](#Rc-dtor-release). -The idiom of having constructors acquire resources and destructors release them is called [RAII](#Rr-raii) ("Resource Acquisition Is Initialization"). +If a constructor acquires a resource (to create a valid object), that resource should be [released by the destructor](#rc-dtor-release). +The idiom of having constructors acquire resources and destructors release them is called [RAII](#rr-raii) ("Resource Acquisition Is Initialization"). -### C.42: If a constructor cannot construct a valid object, throw an exception +### C.42: If a constructor cannot construct a valid object, throw an exception ##### Reason @@ -5586,24 +5586,24 @@ Leaving behind an invalid object and relying on users to consistently check an ` ##### Exception There are domains, such as some hard-real-time systems (think airplane controls) where (without additional tool support) exception handling is not sufficiently predictable from a timing perspective. -There the `is_valid()` technique must be used. In such cases, check `is_valid()` consistently and immediately to simulate [RAII](#Rr-raii). +There the `is_valid()` technique must be used. In such cases, check `is_valid()` consistently and immediately to simulate [RAII](#rr-raii). ##### Alternative If you feel tempted to use some "post-constructor initialization" or "two-stage initialization" idiom, try not to do that. -If you really have to, look at [factory functions](#Rc-factory). +If you really have to, look at [factory functions](#rc-factory). ##### Note One reason people have used `init()` functions rather than doing the initialization work in a constructor has been to avoid code replication. -[Delegating constructors](#Rc-delegating) and [default member initialization](#Rc-in-class-initializer) do that better. -Another reason has been to delay initialization until an object is needed; the solution to that is often [not to declare a variable until it can be properly initialized](#Res-init). +[Delegating constructors](#rc-delegating) and [default member initialization](#rc-in-class-initializer) do that better. +Another reason has been to delay initialization until an object is needed; the solution to that is often [not to declare a variable until it can be properly initialized](#res-init). ##### Enforcement ??? -### C.43: Ensure that a copyable class has a default constructor +### C.43: Ensure that a copyable class has a default constructor ##### Reason @@ -5634,7 +5634,7 @@ However, most realistic `Date` classes have a "first date" (e.g. January 1, 1970 class Date { public: Date(int dd, int mm, int yyyy); - Date() = default; // [See also](#Rc-default) + Date() = default; // [See also](#rc-default) // ... private: int dd {1}; @@ -5723,7 +5723,7 @@ However, it is preferable to have a default constructor default to a meaningful * Flag classes that are comparable with `==` but not copyable -### C.44: Prefer default constructors to be simple and non-throwing +### C.44: Prefer default constructors to be simple and non-throwing ##### Reason @@ -5771,7 +5771,7 @@ Setting a `Vector1` to empty after detecting an error is trivial. * Flag throwing default constructors -### C.45: Don't define a default constructor that only initializes data members; use default member initializers instead +### C.45: Don't define a default constructor that only initializes data members; use default member initializers instead ##### Reason @@ -5801,7 +5801,7 @@ Using default member initializers lets the compiler generate the function for yo (Simple) A default constructor should do more than just initialize data members with constants. -### C.46: By default, declare single-argument constructors explicit +### C.46: By default, declare single-argument constructors explicit ##### Reason @@ -5829,7 +5829,7 @@ If you really want an implicit conversion from the constructor argument type to Complex z = 10.7; // unsurprising conversion -**See also**: [Discussion of implicit conversions](#Ro-conversion) +**See also**: [Discussion of implicit conversions](#ro-conversion) ##### Note @@ -5839,7 +5839,7 @@ Copy and move constructors should not be made `explicit` because they do not per (Simple) Single-argument constructors should be declared `explicit`. Good single argument non-`explicit` constructors are rare in most code bases. Warn for all that are not on a "positive list". -### C.47: Define and initialize data members in the order of member declaration +### C.47: Define and initialize data members in the order of member declaration ##### Reason @@ -5861,9 +5861,9 @@ To minimize confusion and errors. That is the order in which the initialization (Simple) A member initializer list should mention the members in the same order they are declared. -**See also**: [Discussion](#Sd-order) +**See also**: [Discussion](#sd-order) -### C.48: Prefer default member initializers to member initializers in constructors for constant initializers +### C.48: Prefer default member initializers to member initializers in constructors for constant initializers ##### Reason @@ -5912,7 +5912,7 @@ How would a maintainer know whether `j` was deliberately uninitialized (probably * (Simple) Every constructor should initialize every data member (either explicitly, via a delegating ctor call or via default construction). * (Simple) Default arguments to constructors suggest a default member initializer might be more appropriate. -### C.49: Prefer initialization to assignment in constructors +### C.49: Prefer initialization to assignment in constructors ##### Reason @@ -5946,7 +5946,7 @@ An initialization explicitly states that initialization, rather than assignment, ##### Example, better still Instead of those `const char*`s we could use C++17 `std::string_view` or `gsl::span` -as [a more general way to present arguments to a function](#Rstr-view): +as [a more general way to present arguments to a function](#rstr-view): class D { // Good string s1; @@ -5955,7 +5955,7 @@ as [a more general way to present arguments to a function](#Rstr-view): // ... }; -### C.50: Use a factory function if you need "virtual behavior" during initialization +### C.50: Use a factory function if you need "virtual behavior" during initialization ##### Reason @@ -6024,9 +6024,9 @@ By providing the factory function `create()`, we make construction (on the free Conventional factory functions allocate on the free store, rather than on the stack or in an enclosing object. -**See also**: [Discussion](#Sd-factory) +**See also**: [Discussion](#sd-factory) -### C.51: Use delegating constructors to represent common actions for all constructors of a class +### C.51: Use delegating constructors to represent common actions for all constructors of a class ##### Reason @@ -6067,13 +6067,13 @@ The common action gets tedious to write and might accidentally not be common. // ... }; -**See also**: If the "repeated action" is a simple initialization, consider [a default member initializer](#Rc-in-class-initializer). +**See also**: If the "repeated action" is a simple initialization, consider [a default member initializer](#rc-in-class-initializer). ##### Enforcement (Moderate) Look for similar constructor bodies. -### C.52: Use inheriting constructors to import constructors into a derived class that does not need further explicit initialization +### C.52: Use inheriting constructors to import constructors into a derived class that does not need further explicit initialization ##### Reason @@ -6107,17 +6107,17 @@ If you need those constructors for a derived class, re-implementing them is tedi Make sure that every member of the derived class is initialized. -## C.copy: Copy and move +## C.copy: Copy and move Concrete types should generally be copyable, but interfaces in a class hierarchy should not. Resource handles might or might not be copyable. Types can be defined to move for logical as well as performance reasons. -### C.60: Make copy assignment non-`virtual`, take the parameter by `const&`, and return by non-`const&` +### C.60: Make copy assignment non-`virtual`, take the parameter by `const&`, and return by non-`const&` ##### Reason -It is simple and efficient. If you want to optimize for rvalues, provide an overload that takes an `&&` (see [F.18](#Rf-consume)). +It is simple and efficient. If you want to optimize for rvalues, provide an overload that takes an `&&` (see [F.18](#rf-consume)). ##### Example @@ -6171,10 +6171,10 @@ But what if you can get significantly better performance by not making a tempora return *this; } -By writing directly to the target elements, we will get only [the basic guarantee](#Abrahams01) rather than the strong guarantee offered by the `swap` technique. Beware of [self-assignment](#Rc-copy-self). +By writing directly to the target elements, we will get only [the basic guarantee](#Abrahams01) rather than the strong guarantee offered by the `swap` technique. Beware of [self-assignment](#rc-copy-self). **Alternatives**: If you think you need a `virtual` assignment operator, and understand why that's deeply problematic, don't call it `operator=`. Make it a named function like `virtual void assign(const Foo&)`. -See [copy constructor vs. `clone()`](#Rc-copy-virtual). +See [copy constructor vs. `clone()`](#rc-copy-virtual). ##### Enforcement @@ -6183,7 +6183,7 @@ See [copy constructor vs. `clone()`](#Rc-copy-virtual). * (Moderate) An assignment operator should (implicitly or explicitly) invoke all base and member assignment operators. Look at the destructor to determine if the type has pointer semantics or value semantics. -### C.61: A copy operation should copy +### C.61: A copy operation should copy ##### Reason @@ -6254,7 +6254,7 @@ Prefer value semantics unless you are building a "smart pointer". Value semantic (Not enforceable) -### C.62: Make copy assignment safe for self-assignment +### C.62: Make copy assignment safe for self-assignment ##### Reason @@ -6284,7 +6284,7 @@ The default assignment generated from members that handle self-assignment correc ##### Note -You can handle self-assignment by explicitly testing for self-assignment, but often it is faster and more elegant to cope without such a test (e.g., [using `swap`](#Rc-swap)). +You can handle self-assignment by explicitly testing for self-assignment, but often it is faster and more elegant to cope without such a test (e.g., [using `swap`](#rc-swap)). class Foo { string s; @@ -6320,23 +6320,23 @@ Consider: (Simple) Assignment operators should not contain the pattern `if (this == &a) return *this;` ??? -### C.63: Make move assignment non-`virtual`, take the parameter by `&&`, and return by non-`const&` +### C.63: Make move assignment non-`virtual`, take the parameter by `&&`, and return by non-`const&` ##### Reason It is simple and efficient. -**See**: [The rule for copy-assignment](#Rc-copy-assignment). +**See**: [The rule for copy-assignment](#rc-copy-assignment). ##### Enforcement -Equivalent to what is done for [copy-assignment](#Rc-copy-assignment). +Equivalent to what is done for [copy-assignment](#rc-copy-assignment). * (Simple) An assignment operator should not be virtual. Here be dragons! * (Simple) An assignment operator should return `T&` to enable chaining, not alternatives like `const T&` which interfere with composability and putting objects in containers. * (Moderate) A move assignment operator should (implicitly or explicitly) invoke all base and member move assignment operators. -### C.64: A move operation should move and leave its source in a valid state +### C.64: A move operation should move and leave its source in a valid state ##### Reason @@ -6390,7 +6390,7 @@ Unless there is an exceptionally strong reason not to, make `x = std::move(y); y (Not enforceable) Look for assignments to members in the move operation. If there is a default constructor, compare those assignments to the initializations in the default constructor. -### C.65: Make move assignment safe for self-assignment +### C.65: Make move assignment safe for self-assignment ##### Reason @@ -6414,7 +6414,7 @@ If `x = x` changes the value of `x`, people will be surprised and bad errors can return *this; } -The one-in-a-million argument against `if (this == &a) return *this;` tests from the discussion of [self-assignment](#Rc-copy-self) is even more relevant for self-move. +The one-in-a-million argument against `if (this == &a) return *this;` tests from the discussion of [self-assignment](#rc-copy-self) is even more relevant for self-move. ##### Note @@ -6439,7 +6439,7 @@ Here is a way to move a pointer without a test (imagine it as code in the implem * (Moderate) In the case of self-assignment, a move assignment operator should not leave the object holding pointer members that have been `delete`d or set to `nullptr`. * (Not enforceable) Look at the use of standard-library container types (incl. `string`) and consider them safe for ordinary (not life-critical) uses. -### C.66: Make move operations `noexcept` +### C.66: Make move operations `noexcept` ##### Reason @@ -6487,7 +6487,7 @@ This `Vector2` is not just inefficient, but since a vector copy requires allocat (Simple) A move operation should be marked `noexcept`. -### C.67: A polymorphic class should suppress public copy/move +### C.67: A polymorphic class should suppress public copy/move ##### Reason @@ -6544,7 +6544,7 @@ If the class has no data, `=delete` the copy/move functions. Otherwise, make the ##### Note -If you need to create deep copies of polymorphic objects, use `clone()` functions: see [C.130](#Rh-copy). +If you need to create deep copies of polymorphic objects, use `clone()` functions: see [C.130](#rh-copy). ##### Exception @@ -6561,7 +6561,7 @@ In addition to the operations for which the language offers default implementati there are a few operations that are so foundational that specific rules for their definition are needed: comparisons, `swap`, and `hash`. -### C.80: Use `=default` if you have to be explicit about using the default semantics +### C.80: Use `=default` if you have to be explicit about using the default semantics ##### Reason @@ -6603,7 +6603,7 @@ Writing out the bodies of the copy and move operations is verbose, tedious, and (Moderate) The body of a user-defined operation should not have the same semantics as the compiler-generated version, because that would be redundant. -### C.81: Use `=delete` when you want to disable default behavior (without wanting an alternative) +### C.81: Use `=delete` when you want to disable default behavior (without wanting an alternative) ##### Reason @@ -6655,7 +6655,7 @@ Note that deleted functions should be public. The elimination of a default operation is (should be) based on the desired semantics of the class. Consider such classes suspect, but maintain a "positive list" of classes where a human has asserted that the semantics is correct. -### C.82: Don't call virtual functions in constructors and destructors +### C.82: Don't call virtual functions in constructors and destructors ##### Reason @@ -6696,7 +6696,7 @@ Worse, a direct or indirect call to an unimplemented pure virtual function from Note that calling a specific explicitly qualified function is not a virtual call even if the function is `virtual`. -**See also** [factory functions](#Rc-factory) for how to achieve the effect of a call to a derived class function without risking undefined behavior. +**See also** [factory functions](#rc-factory) for how to achieve the effect of a call to a derived class function without risking undefined behavior. ##### Note @@ -6708,11 +6708,11 @@ However, experience shows that such calls are rarely needed, easily confuse main * Flag calls of virtual functions from constructors and destructors. -### C.83: For value-like types, consider providing a `noexcept` swap function +### C.83: For value-like types, consider providing a `noexcept` swap function ##### Reason -A `swap` can be handy for implementing a number of idioms, from smoothly moving objects around to implementing assignment easily to providing a guaranteed commit function that enables strongly error-safe calling code. Consider using swap to implement copy assignment in terms of copy construction. See also [destructors, deallocation, and swap must never fail](#Re-never-fail). +A `swap` can be handy for implementing a number of idioms, from smoothly moving objects around to implementing assignment easily to providing a guaranteed commit function that enables strongly error-safe calling code. Consider using swap to implement copy assignment in terms of copy construction. See also [destructors, deallocation, and swap must never fail](#re-never-fail). ##### Example, good @@ -6740,7 +6740,7 @@ Providing a non-member `swap` function in the same namespace as your type for ca * Non-trivially copyable types should provide a member swap or a free swap overload. * (Simple) When a class has a `swap` member function, it should be declared `noexcept`. -### C.84: A `swap` function must not fail +### C.84: A `swap` function must not fail ##### Reason @@ -6761,18 +6761,18 @@ This is not just slow, but if a memory allocation occurs for the elements in `tm (Simple) When a class has a `swap` member function, it should be declared `noexcept`. -### C.85: Make `swap` `noexcept` +### C.85: Make `swap` `noexcept` ##### Reason - [A `swap` must not fail](#Rc-swap-fail). + [A `swap` must not fail](#rc-swap-fail). If a `swap` tries to exit with an exception, it's a bad design error and the program had better terminate. ##### Enforcement (Simple) When a class has a `swap` member function, it should be declared `noexcept`. -### C.86: Make `==` symmetric with respect to operand types and `noexcept` +### C.86: Make `==` symmetric with respect to operand types and `noexcept` ##### Reason @@ -6817,7 +6817,7 @@ This rule applies to all the usual comparison operators: `!=`, `<`, `<=`, `>`, a * Flag an `operator==()` for which the argument types differ; same for other comparison operators: `!=`, `<`, `<=`, `>`, and `>=`. * Flag member `operator==()`s; same for other comparison operators: `!=`, `<`, `<=`, `>`, and `>=`. -### C.87: Beware of `==` on base classes +### C.87: Beware of `==` on base classes ##### Reason @@ -6867,7 +6867,7 @@ This rule applies to all the usual comparison operators: `!=`, `<`, `<=`, `>`, ` * Flag a virtual `operator==()`; same for other comparison operators: `!=`, `<`, `<=`, `>`, `>=`, and `<=>`. -### C.89: Make a `hash` `noexcept` +### C.89: Make a `hash` `noexcept` ##### Reason @@ -6904,11 +6904,11 @@ That tends to work better than "cleverness" for non-specialists. * Flag throwing `hash`es. -### C.90: Rely on constructors and assignment operators, not `memset` and `memcpy` +### C.90: Rely on constructors and assignment operators, not `memset` and `memcpy` ##### Reason -The standard C++ mechanism to construct an instance of a type is to call its constructor. As specified in guideline [C.41](#Rc-complete): a constructor should create a fully initialized object. No additional initialization, such as by `memcpy`, should be required. +The standard C++ mechanism to construct an instance of a type is to call its constructor. As specified in guideline [C.41](#rc-complete): a constructor should create a fully initialized object. No additional initialization, such as by `memcpy`, should be required. A type will provide a copy constructor and/or copy assignment operator to appropriately make a copy of the class, preserving the type's invariants. Using memcpy to copy a non-trivially copyable type has undefined behavior. Frequently this results in slicing, or data corruption. ##### Example, good @@ -6944,25 +6944,25 @@ This is also type-unsafe and overwrites the vtable. * Flag passing a non-trivially-copyable type to `memset` or `memcpy`. -## C.con: Containers and other resource handles +## C.con: Containers and other resource handles A container is an object holding a sequence of objects of some type; `std::vector` is the archetypical container. A resource handle is a class that owns a resource; `std::vector` is the typical resource handle; its resource is its sequence of elements. Summary of container rules: -* [C.100: Follow the STL when defining a container](#Rcon-stl) -* [C.101: Give a container value semantics](#Rcon-val) -* [C.102: Give a container move operations](#Rcon-move) -* [C.103: Give a container an initializer list constructor](#Rcon-init) -* [C.104: Give a container a default constructor that sets it to empty](#Rcon-empty) +* [C.100: Follow the STL when defining a container](#rcon-stl) +* [C.101: Give a container value semantics](#rcon-val) +* [C.102: Give a container move operations](#rcon-move) +* [C.103: Give a container an initializer list constructor](#rcon-init) +* [C.104: Give a container a default constructor that sets it to empty](#rcon-empty) * ??? -* [C.109: If a resource handle has pointer semantics, provide `*` and `->`](#Rcon-ptr) +* [C.109: If a resource handle has pointer semantics, provide `*` and `->`](#rcon-ptr) -**See also**: [Resources](#S-resource) +**See also**: [Resources](#s-resource) -### C.100: Follow the STL when defining a container +### C.100: Follow the STL when defining a container ##### Reason @@ -7023,7 +7023,7 @@ Here, special constructors from `std::vector` were added. ??? -### C.101: Give a container value semantics +### C.101: Give a container value semantics ##### Reason @@ -7049,7 +7049,7 @@ In particular, ensure that an object compares equal to its copy. ??? -### C.102: Give a container move operations +### C.102: Give a container move operations ##### Reason @@ -7073,7 +7073,7 @@ A user can reasonably assume that returning a standard-like container is cheap. ??? -### C.103: Give a container an initializer list constructor +### C.103: Give a container an initializer list constructor ##### Reason @@ -7088,7 +7088,7 @@ Familiarity. ??? -### C.104: Give a container a default constructor that sets it to empty +### C.104: Give a container a default constructor that sets it to empty ##### Reason @@ -7102,7 +7102,7 @@ To make it `Regular`. ??? -### C.109: If a resource handle has pointer semantics, provide `*` and `->` +### C.109: If a resource handle has pointer semantics, provide `*` and `->` ##### Reason @@ -7117,22 +7117,22 @@ Familiarity. ??? -## C.lambdas: Function objects and lambdas +## C.lambdas: Function objects and lambdas A function object is an object supplying an overloaded `()` so that you can call it. A lambda expression (colloquially often shortened to "a lambda") is a notation for generating a function object. -Function objects should be cheap to copy (and therefore [passed by value](#Rf-in)). +Function objects should be cheap to copy (and therefore [passed by value](#rf-in)). Summary: -* [F.10: If an operation can be reused, give it a name](#Rf-name) -* [F.11: Use an unnamed lambda if you need a simple function object in one place only](#Rf-lambda) -* [F.50: Use a lambda when a function won't do (to capture local variables, or to write a local function)](#Rf-capture-vs-overload) -* [F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms](#Rf-reference-capture) -* [F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread](#Rf-value-capture) -* [ES.28: Use lambdas for complex initialization, especially of `const` variables](#Res-lambda-init) +* [F.10: If an operation can be reused, give it a name](#rf-name) +* [F.11: Use an unnamed lambda if you need a simple function object in one place only](#rf-lambda) +* [F.50: Use a lambda when a function won't do (to capture local variables, or to write a local function)](#rf-capture-vs-overload) +* [F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms](#rf-reference-capture) +* [F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread](#rf-value-capture) +* [ES.28: Use lambdas for complex initialization, especially of `const` variables](#res-lambda-init) -## C.hier: Class hierarchies (OOP) +## C.hier: Class hierarchies (OOP) A class hierarchy is constructed to represent a set of hierarchically organized concepts (only). Typically base classes act as interfaces. @@ -7140,41 +7140,41 @@ There are two major uses for hierarchies, often named implementation inheritance Class hierarchy rule summary: -* [C.120: Use class hierarchies to represent concepts with inherent hierarchical structure (only)](#Rh-domain) -* [C.121: If a base class is used as an interface, make it a pure abstract class](#Rh-abstract) -* [C.122: Use abstract classes as interfaces when complete separation of interface and implementation is needed](#Rh-separation) +* [C.120: Use class hierarchies to represent concepts with inherent hierarchical structure (only)](#rh-domain) +* [C.121: If a base class is used as an interface, make it a pure abstract class](#rh-abstract) +* [C.122: Use abstract classes as interfaces when complete separation of interface and implementation is needed](#rh-separation) Designing rules for classes in a hierarchy summary: -* [C.126: An abstract class typically doesn't need a user-written constructor](#Rh-abstract-ctor) -* [C.127: A class with a virtual function should have a virtual or protected destructor](#Rh-dtor) -* [C.128: Virtual functions should specify exactly one of `virtual`, `override`, or `final`](#Rh-override) -* [C.129: When designing a class hierarchy, distinguish between implementation inheritance and interface inheritance](#Rh-kind) -* [C.130: For making deep copies of polymorphic classes prefer a virtual `clone` function instead of public copy construction/assignment](#Rh-copy) -* [C.131: Avoid trivial getters and setters](#Rh-get) -* [C.132: Don't make a function `virtual` without reason](#Rh-virtual) -* [C.133: Avoid `protected` data](#Rh-protected) -* [C.134: Ensure all non-`const` data members have the same access level](#Rh-public) -* [C.135: Use multiple inheritance to represent multiple distinct interfaces](#Rh-mi-interface) -* [C.136: Use multiple inheritance to represent the union of implementation attributes](#Rh-mi-implementation) -* [C.137: Use `virtual` bases to avoid overly general base classes](#Rh-vbase) -* [C.138: Create an overload set for a derived class and its bases with `using`](#Rh-using) -* [C.139: Use `final` on classes sparingly](#Rh-final) -* [C.140: Do not provide different default arguments for a virtual function and an overrider](#Rh-virtual-default-arg) +* [C.126: An abstract class typically doesn't need a user-written constructor](#rh-abstract-ctor) +* [C.127: A class with a virtual function should have a virtual or protected destructor](#rh-dtor) +* [C.128: Virtual functions should specify exactly one of `virtual`, `override`, or `final`](#rh-override) +* [C.129: When designing a class hierarchy, distinguish between implementation inheritance and interface inheritance](#rh-kind) +* [C.130: For making deep copies of polymorphic classes prefer a virtual `clone` function instead of public copy construction/assignment](#rh-copy) +* [C.131: Avoid trivial getters and setters](#rh-get) +* [C.132: Don't make a function `virtual` without reason](#rh-virtual) +* [C.133: Avoid `protected` data](#rh-protected) +* [C.134: Ensure all non-`const` data members have the same access level](#rh-public) +* [C.135: Use multiple inheritance to represent multiple distinct interfaces](#rh-mi-interface) +* [C.136: Use multiple inheritance to represent the union of implementation attributes](#rh-mi-implementation) +* [C.137: Use `virtual` bases to avoid overly general base classes](#rh-vbase) +* [C.138: Create an overload set for a derived class and its bases with `using`](#rh-using) +* [C.139: Use `final` on classes sparingly](#rh-final) +* [C.140: Do not provide different default arguments for a virtual function and an overrider](#rh-virtual-default-arg) Accessing objects in a hierarchy rule summary: -* [C.145: Access polymorphic objects through pointers and references](#Rh-poly) -* [C.146: Use `dynamic_cast` where class hierarchy navigation is unavoidable](#Rh-dynamic_cast) -* [C.147: Use `dynamic_cast` to a reference type when failure to find the required class is considered an error](#Rh-ref-cast) -* [C.148: Use `dynamic_cast` to a pointer type when failure to find the required class is considered a valid alternative](#Rh-ptr-cast) -* [C.149: Use `unique_ptr` or `shared_ptr` to avoid forgetting to `delete` objects created using `new`](#Rh-smart) -* [C.150: Use `make_unique()` to construct objects owned by `unique_ptr`s](#Rh-make_unique) -* [C.151: Use `make_shared()` to construct objects owned by `shared_ptr`s](#Rh-make_shared) -* [C.152: Never assign a pointer to an array of derived class objects to a pointer to its base](#Rh-array) -* [C.153: Prefer virtual function to casting](#Rh-use-virtual) +* [C.145: Access polymorphic objects through pointers and references](#rh-poly) +* [C.146: Use `dynamic_cast` where class hierarchy navigation is unavoidable](#rh-dynamic_cast) +* [C.147: Use `dynamic_cast` to a reference type when failure to find the required class is considered an error](#rh-ref-cast) +* [C.148: Use `dynamic_cast` to a pointer type when failure to find the required class is considered a valid alternative](#rh-ptr-cast) +* [C.149: Use `unique_ptr` or `shared_ptr` to avoid forgetting to `delete` objects created using `new`](#rh-smart) +* [C.150: Use `make_unique()` to construct objects owned by `unique_ptr`s](#rh-make_unique) +* [C.151: Use `make_shared()` to construct objects owned by `shared_ptr`s](#rh-make_shared) +* [C.152: Never assign a pointer to an array of derived class objects to a pointer to its base](#rh-array) +* [C.153: Prefer virtual function to casting](#rh-use-virtual) -### C.120: Use class hierarchies to represent concepts with inherent hierarchical structure (only) +### C.120: Use class hierarchies to represent concepts with inherent hierarchical structure (only) ##### Reason @@ -7239,7 +7239,7 @@ not using this (over)general interface in favor of a particular interface found * Look for classes with lots of members that do nothing but throw. * Flag every use of a non-public base class `B` where the derived class `D` does not override a virtual function or access a protected member in `B`, and `B` is not one of the following: empty, a template parameter or parameter pack of `D`, a class template specialized with `D`. -### C.121: If a base class is used as an interface, make it a pure abstract class +### C.121: If a base class is used as an interface, make it a pure abstract class ##### Reason @@ -7282,7 +7282,7 @@ Give `Goof` a virtual destructor and all is well. * Warn on any class that contains data members and also has an overridable (non-`final`) virtual function that wasn't inherited from a base class. -### C.122: Use abstract classes as interfaces when complete separation of interface and implementation is needed +### C.122: Use abstract classes as interfaces when complete separation of interface and implementation is needed ##### Reason @@ -7319,7 +7319,7 @@ Furthermore, we can update `D1` and `D2` in ways that are not binary compatible ## C.hierclass: Designing classes in a hierarchy: -### C.126: An abstract class typically doesn't need a user-written constructor +### C.126: An abstract class typically doesn't need a user-written constructor ##### Reason @@ -7352,11 +7352,11 @@ An abstract class typically does not have any data for a constructor to initiali Flag abstract classes with constructors. -### C.127: A class with a virtual function should have a virtual or protected destructor +### C.127: A class with a virtual function should have a virtual or protected destructor ##### Reason -A class with a virtual function is usually (and in general) used via a pointer to base. Usually, the last user has to call delete on a pointer to base, often via a smart pointer to base, so the destructor should be public and virtual. Less commonly, if deletion through a pointer to base is not intended to be supported, the destructor should be protected and non-virtual; see [C.35](#Rc-dtor-virtual). +A class with a virtual function is usually (and in general) used via a pointer to base. Usually, the last user has to call delete on a pointer to base, often via a smart pointer to base, so the destructor should be public and virtual. Less commonly, if deletion through a pointer to base is not intended to be supported, the destructor should be protected and non-virtual; see [C.35](#rc-dtor-virtual). ##### Example, bad @@ -7386,7 +7386,7 @@ There are people who don't follow this rule because they plan to use a class onl * A class with any virtual functions should have a destructor that is either public and virtual or else protected and non-virtual. * Flag `delete` of a class with a virtual function but no virtual destructor. -### C.128: Virtual functions should specify exactly one of `virtual`, `override`, or `final` +### C.128: Virtual functions should specify exactly one of `virtual`, `override`, or `final` ##### Reason @@ -7442,7 +7442,7 @@ Note: Use `final` on functions sparingly. It does not necessarily lead to optimi * Flag overrides with neither `override` nor `final`. * Flag function declarations that use more than one of `virtual`, `override`, and `final`. -### C.129: When designing a class hierarchy, distinguish between implementation inheritance and interface inheritance +### C.129: When designing a class hierarchy, distinguish between implementation inheritance and interface inheritance ##### Reason @@ -7459,7 +7459,7 @@ in particular to allow derived classes to be added and changed without affecting * implementation inheritance is the use of inheritance to simplify implementation of new facilities by making useful operations available for implementers of related new operations (sometimes called "programming by difference"). -A pure interface class is simply a set of pure virtual functions; see [I.25](#Ri-abstract). +A pure interface class is simply a set of pure virtual functions; see [I.25](#ri-abstract). In early OOP (e.g., in the 1980s and 1990s), implementation inheritance and interface inheritance were often mixed and bad habits die hard. @@ -7658,7 +7658,7 @@ or if direct use of a member offers optimization opportunities (e.g., if an impl ##### Note -Another (related) technique for separating interface and implementation is [Pimpl](#Ri-pimpl). +Another (related) technique for separating interface and implementation is [Pimpl](#ri-pimpl). ##### Note @@ -7674,11 +7674,11 @@ at the cost of the functionality being available only to users of the hierarchy. * ??? -### C.130: For making deep copies of polymorphic classes prefer a virtual `clone` function instead of public copy construction/assignment +### C.130: For making deep copies of polymorphic classes prefer a virtual `clone` function instead of public copy construction/assignment ##### Reason -Copying a polymorphic class is discouraged due to the slicing problem, see [C.67](#Rc-copy-virtual). If you really need copy semantics, copy deeply: Provide a virtual `clone` function that will copy the actual most-derived type and return an owning pointer to the new object, and then in derived classes return the derived type (use a covariant return type). +Copying a polymorphic class is discouraged due to the slicing problem, see [C.67](#rc-copy-virtual). If you really need copy semantics, copy deeply: Provide a virtual `clone` function that will copy the actual most-derived type and return an owning pointer to the new object, and then in derived classes return the derived type (use a covariant return type). ##### Example @@ -7703,11 +7703,11 @@ Copying a polymorphic class is discouraged due to the slicing problem, see [C.67 }; }; -Generally, it is recommended to use smart pointers to represent ownership (see [R.20](#Rr-owner)). However, because of language rules, the covariant return type cannot be a smart pointer: `D::clone` can't return a `unique_ptr` while `B::clone` returns `unique_ptr`. Therefore, you either need to consistently return `unique_ptr` in all overrides, or use `owner<>` utility from the [Guidelines Support Library](#SS-views). +Generally, it is recommended to use smart pointers to represent ownership (see [R.20](#rr-owner)). However, because of language rules, the covariant return type cannot be a smart pointer: `D::clone` can't return a `unique_ptr` while `B::clone` returns `unique_ptr`. Therefore, you either need to consistently return `unique_ptr` in all overrides, or use `owner<>` utility from the [Guidelines Support Library](#ss-views). -### C.131: Avoid trivial getters and setters +### C.131: Avoid trivial getters and setters ##### Reason @@ -7734,7 +7734,7 @@ Consider making such a class a `struct` -- that is, a behaviorless bunch of vari int y {0}; }; -Note that we can put default initializers on data members: [C.49: Prefer initialization to assignment in constructors](#Rc-initialize). +Note that we can put default initializers on data members: [C.49: Prefer initialization to assignment in constructors](#rc-initialize). ##### Note @@ -7744,7 +7744,7 @@ The key to this rule is whether the semantics of the getter/setter are trivial. Flag multiple `get` and `set` member functions that simply access a member without additional semantics. -### C.132: Don't make a function `virtual` without reason +### C.132: Don't make a function `virtual` without reason ##### Reason @@ -7771,7 +7771,7 @@ This kind of "vector" isn't meant to be used as a base class at all. * Flag a class with virtual functions but no derived classes. * Flag a class where all member functions are virtual and have implementations. -### C.133: Avoid `protected` data +### C.133: Avoid `protected` data **Alternative formulation**: Make member data `public` or (preferably) `private`. @@ -7806,8 +7806,8 @@ The protected data has de facto become global to a large body of code. Protected data often looks tempting to enable arbitrary improvements through derivation. Often, what you get is unprincipled changes and errors. -[Prefer `private` data](#Rc-private) with a well-specified and enforced invariant. -Alternatively, and often better, [keep data out of any class used as an interface](#Rh-abstract). +[Prefer `private` data](#rc-private) with a well-specified and enforced invariant. +Alternatively, and often better, [keep data out of any class used as an interface](#rh-abstract). ##### Note @@ -7817,7 +7817,7 @@ Protected member function can be just fine. Flag classes with `protected` data. -### C.134: Ensure all non-`const` data members have the same access level +### C.134: Ensure all non-`const` data members have the same access level ##### Reason @@ -7841,7 +7841,7 @@ Data members in category B should be `private` or `const`. This is because encap Most classes are either all A or all B: * *All public*: If you're writing an aggregate bundle-of-variables without an invariant across those variables, then all the variables should be `public`. - [By convention, declare such classes `struct` rather than `class`](#Rc-struct) + [By convention, declare such classes `struct` rather than `class`](#rc-struct) * *All private*: If you're writing a type that maintains an invariant, then all the non-`const` variables should be private -- it should be encapsulated. ##### Exception @@ -7852,7 +7852,7 @@ Occasionally classes will mix A and B, usually for debug reasons. An encapsulate Flag any class that has non-`const` data members with different access levels. -### C.135: Use multiple inheritance to represent multiple distinct interfaces +### C.135: Use multiple inheritance to represent multiple distinct interfaces ##### Reason @@ -7881,7 +7881,7 @@ Such interfaces are typically abstract classes. ??? -### C.136: Use multiple inheritance to represent the union of implementation attributes +### C.136: Use multiple inheritance to represent the union of implementation attributes ##### Reason @@ -7912,7 +7912,7 @@ or various bases from boost.intrusive (e.g. `list_base_hook` or `intrusive_ref_c ??? -### C.137: Use `virtual` bases to avoid overly general base classes +### C.137: Use `virtual` bases to avoid overly general base classes ##### Reason @@ -7953,8 +7953,8 @@ Factoring out `Utility` makes sense if many derived classes share significant "i ##### Note Obviously, the example is too "theoretical", but it is hard to find a *small* realistic example. -`Interface` is the root of an [interface hierarchy](#Rh-abstract) -and `Utility` is the root of an [implementation hierarchy](#Rh-kind). +`Interface` is the root of an [interface hierarchy](#rh-abstract) +and `Utility` is the root of an [implementation hierarchy](#rh-kind). Here is [a slightly more realistic example](https://www.quora.com/What-are-the-uses-and-advantages-of-virtual-base-class-in-C%2B%2B/answer/Lance-Diduck) with an explanation. ##### Note @@ -7965,7 +7965,7 @@ Often, linearization of a hierarchy is a better solution. Flag mixed interface and implementation hierarchies. -### C.138: Create an overload set for a derived class and its bases with `using` +### C.138: Create an overload set for a derived class and its bases with `using` ##### Reason @@ -8014,7 +8014,7 @@ For variadic bases, C++17 introduced a variadic form of the using-declaration, Diagnose name hiding -### C.139: Use `final` on classes sparingly +### C.139: Use `final` on classes sparingly ##### Reason @@ -8050,7 +8050,7 @@ However, misuses are (or at least have been) far more common. Flag uses of `final` on classes. -### C.140: Do not provide different default arguments for a virtual function and an overrider +### C.140: Do not provide different default arguments for a virtual function and an overrider ##### Reason @@ -8081,7 +8081,7 @@ Flag default arguments on virtual functions if they differ between base and deri ## C.hier-access: Accessing objects in a hierarchy -### C.145: Access polymorphic objects through pointers and references +### C.145: Access polymorphic objects through pointers and references ##### Reason @@ -8119,13 +8119,13 @@ You can safely access a named polymorphic object in the scope of its definition, ##### See also -[A polymorphic class should suppress copying](#Rc-copy-virtual) +[A polymorphic class should suppress copying](#rc-copy-virtual) ##### Enforcement Flag all slicing. -### C.146: Use `dynamic_cast` where class hierarchy navigation is unavoidable +### C.146: Use `dynamic_cast` where class hierarchy navigation is unavoidable ##### Reason @@ -8184,7 +8184,7 @@ Use of the other casts can violate type safety and cause the program to access a ##### Note Like other casts, `dynamic_cast` is overused. -[Prefer virtual functions to casting](#Rh-use-virtual). +[Prefer virtual functions to casting](#rh-use-virtual). Prefer [static polymorphism](#???) to hierarchy navigation where it is possible (no run-time resolution necessary) and reasonably convenient. @@ -8260,9 +8260,9 @@ Consider: ##### Enforcement * Flag all uses of `static_cast` for downcasts, including C-style casts that perform a `static_cast`. -* This rule is part of the [type-safety profile](#Pro-type-downcast). +* This rule is part of the [type-safety profile](#pro-type-downcast). -### C.147: Use `dynamic_cast` to a reference type when failure to find the required class is considered an error +### C.147: Use `dynamic_cast` to a reference type when failure to find the required class is considered an error ##### Reason @@ -8279,13 +8279,13 @@ Casting to a reference expresses that you intend to end up with a valid object, ??? -### C.148: Use `dynamic_cast` to a pointer type when failure to find the required class is considered a valid alternative +### C.148: Use `dynamic_cast` to a pointer type when failure to find the required class is considered a valid alternative ##### Reason The `dynamic_cast` conversion allows to test whether a pointer is pointing at a polymorphic object that has a given class in its hierarchy. Since failure to find the class merely returns a null value, it can be tested during run time. This allows writing code that can choose alternative paths depending on the results. -Contrast with [C.147](#Rh-ref-cast), where failure is an error, and should not be used for conditional execution. +Contrast with [C.147](#rh-ref-cast), where failure is an error, and should not be used for conditional execution. ##### Example @@ -8319,7 +8319,7 @@ Therefore the result of the `dynamic_cast` should always be treated as if it mig * (Complex) Unless there is a null test on the result of a `dynamic_cast` of a pointer type, warn upon dereference of the pointer. -### C.149: Use `unique_ptr` or `shared_ptr` to avoid forgetting to `delete` objects created using `new` +### C.149: Use `unique_ptr` or `shared_ptr` to avoid forgetting to `delete` objects created using `new` ##### Reason @@ -8340,15 +8340,15 @@ Avoid resource leaks. * Flag initialization of a naked pointer with the result of a `new` * Flag `delete` of local variable -### C.150: Use `make_unique()` to construct objects owned by `unique_ptr`s +### C.150: Use `make_unique()` to construct objects owned by `unique_ptr`s -See [R.23](#Rr-make_unique) +See [R.23](#rr-make_unique) -### C.151: Use `make_shared()` to construct objects owned by `shared_ptr`s +### C.151: Use `make_shared()` to construct objects owned by `shared_ptr`s -See [R.22](#Rr-make_shared) +See [R.22](#rr-make_shared) -### C.152: Never assign a pointer to an array of derived class objects to a pointer to its base +### C.152: Never assign a pointer to an array of derived class objects to a pointer to its base ##### Reason @@ -8373,7 +8373,7 @@ Subscripting the resulting base pointer will lead to invalid object access and p * Pass an array as a `span` rather than as a pointer, and don't let the array name suffer a derived-to-base conversion before getting into the `span` -### C.153: Prefer virtual function to casting +### C.153: Prefer virtual function to casting ##### Reason @@ -8387,27 +8387,27 @@ give a wrong result (especially as a hierarchy is modified during maintenance). ##### Enforcement -See [C.146](#Rh-dynamic_cast) and ??? +See [C.146](#rh-dynamic_cast) and ??? -## C.over: Overloading and overloaded operators +## C.over: Overloading and overloaded operators You can overload ordinary functions, function templates, and operators. You cannot overload function objects. Overload rule summary: -* [C.160: Define operators primarily to mimic conventional usage](#Ro-conventional) -* [C.161: Use non-member functions for symmetric operators](#Ro-symmetric) -* [C.162: Overload operations that are roughly equivalent](#Ro-equivalent) -* [C.163: Overload only for operations that are roughly equivalent](#Ro-equivalent-2) -* [C.164: Avoid implicit conversion operators](#Ro-conversion) -* [C.165: Use `using` for customization points](#Ro-custom) -* [C.166: Overload unary `&` only as part of a system of smart pointers and references](#Ro-address-of) -* [C.167: Use an operator for an operation with its conventional meaning](#Ro-overload) -* [C.168: Define overloaded operators in the namespace of their operands](#Ro-namespace) -* [C.170: If you feel like overloading a lambda, use a generic lambda](#Ro-lambda) +* [C.160: Define operators primarily to mimic conventional usage](#ro-conventional) +* [C.161: Use non-member functions for symmetric operators](#ro-symmetric) +* [C.162: Overload operations that are roughly equivalent](#ro-equivalent) +* [C.163: Overload only for operations that are roughly equivalent](#ro-equivalent-2) +* [C.164: Avoid implicit conversion operators](#ro-conversion) +* [C.165: Use `using` for customization points](#ro-custom) +* [C.166: Overload unary `&` only as part of a system of smart pointers and references](#ro-address-of) +* [C.167: Use an operator for an operation with its conventional meaning](#ro-overload) +* [C.168: Define overloaded operators in the namespace of their operands](#ro-namespace) +* [C.170: If you feel like overloading a lambda, use a generic lambda](#ro-lambda) -### C.160: Define operators primarily to mimic conventional usage +### C.160: Define operators primarily to mimic conventional usage ##### Reason @@ -8424,7 +8424,7 @@ Minimize surprises. // ... }; -Here, the conventional semantics is maintained: [Copies compare equal](#SS-copy). +Here, the conventional semantics is maintained: [Copies compare equal](#ss-copy). ##### Example, bad @@ -8432,14 +8432,14 @@ Here, the conventional semantics is maintained: [Copies compare equal](#SS-copy) ##### Note -Non-member operators should be either friends or defined in [the same namespace as their operands](#Ro-namespace). -[Binary operators should treat their operands equivalently](#Ro-symmetric). +Non-member operators should be either friends or defined in [the same namespace as their operands](#ro-namespace). +[Binary operators should treat their operands equivalently](#ro-symmetric). ##### Enforcement Possibly impossible. -### C.161: Use non-member functions for symmetric operators +### C.161: Use non-member functions for symmetric operators ##### Reason @@ -8454,7 +8454,7 @@ Unless you use a non-member function for (say) `==`, `a == b` and `b == a` will Flag member operator functions. -### C.162: Overload operations that are roughly equivalent +### C.162: Overload operations that are roughly equivalent ##### Reason @@ -8480,7 +8480,7 @@ These three functions all print their arguments (appropriately). Adding to the n ??? -### C.163: Overload only for operations that are roughly equivalent +### C.163: Overload only for operations that are roughly equivalent ##### Reason @@ -8509,7 +8509,7 @@ Be particularly careful about common and popular names, such as `open`, `move`, ??? -### C.164: Avoid implicit conversion operators +### C.164: Avoid implicit conversion operators ##### Reason @@ -8558,7 +8558,7 @@ The string returned by `ff()` is destroyed before the returned pointer into it c Flag all non-explicit conversion operators. -### C.165: Use `using` for customization points +### C.165: Use `using` for customization points ##### Reason @@ -8605,7 +8605,7 @@ This is done by including the general function in the lookup for the function: Unlikely, except for known customization points, such as `swap`. The problem is that the unqualified and qualified lookups both have uses. -### C.166: Overload unary `&` only as part of a system of smart pointers and references +### C.166: Overload unary `&` only as part of a system of smart pointers and references ##### Reason @@ -8639,7 +8639,7 @@ Note that `std::addressof()` always yields a built-in pointer. Tricky. Warn if `&` is user-defined without also defining `->` for the result type. -### C.167: Use an operator for an operation with its conventional meaning +### C.167: Use an operator for an operation with its conventional meaning ##### Reason @@ -8678,7 +8678,7 @@ Don't define those unconventionally and don't invent your own names for them. Tricky. Requires semantic insight. -### C.168: Define overloaded operators in the namespace of their operands +### C.168: Define overloaded operators in the namespace of their operands ##### Reason @@ -8735,13 +8735,13 @@ This might be something best avoided. ##### See also -This is a special case of the rule that [helper functions should be defined in the same namespace as their class](#Rc-helper). +This is a special case of the rule that [helper functions should be defined in the same namespace as their class](#rc-helper). ##### Enforcement * Flag operator definitions that are not in the namespace of their operands -### C.170: If you feel like overloading a lambda, use a generic lambda +### C.170: If you feel like overloading a lambda, use a generic lambda ##### Reason @@ -8762,7 +8762,7 @@ You cannot overload by defining two different lambdas with the same name. The compiler catches the attempt to overload a lambda. -## C.union: Unions +## C.union: Unions A `union` is a `struct` where all members start at the same address so that it can hold only one member at a time. A `union` does not keep track of which member is stored so the programmer has to get it right; @@ -8772,13 +8772,13 @@ A type that is a `union` plus an indicator of which member is currently held is Union rule summary: -* [C.180: Use `union`s to save Memory](#Ru-union) -* [C.181: Avoid "naked" `union`s](#Ru-naked) -* [C.182: Use anonymous `union`s to implement tagged unions](#Ru-anonymous) -* [C.183: Don't use a `union` for type punning](#Ru-pun) +* [C.180: Use `union`s to save Memory](#ru-union) +* [C.181: Avoid "naked" `union`s](#ru-naked) +* [C.182: Use anonymous `union`s to implement tagged unions](#ru-anonymous) +* [C.183: Don't use a `union` for type punning](#ru-pun) * ??? -### C.180: Use `union`s to save memory +### C.180: Use `union`s to save memory ##### Reason @@ -8797,7 +8797,7 @@ Consequently, it can be used to save memory when we have several objects that ar v.d = 987.654; // now v holds a double cout << v.d << '\n'; // write 987.654 -But heed the warning: [Avoid "naked" `union`s](#Ru-naked) +But heed the warning: [Avoid "naked" `union`s](#ru-naked) ##### Example @@ -8844,7 +8844,7 @@ But heed the warning: [Avoid "naked" `union`s](#Ru-naked) ??? -### C.181: Avoid "naked" `union`s +### C.181: Avoid "naked" `union`s ##### Reason @@ -8891,7 +8891,7 @@ The C++17 `variant` type (found in ``) does that for you: ??? -### C.182: Use anonymous `union`s to implement tagged unions +### C.182: Use anonymous `union`s to implement tagged unions ##### Reason @@ -8992,7 +8992,7 @@ Saving programmers from having to write such code is one reason for including `v ??? -### C.183: Don't use a `union` for type punning +### C.183: Don't use a `union` for type punning ##### Reason @@ -9040,23 +9040,23 @@ C++17 introduced a distinct type `std::byte` to facilitate operations on raw obj -# Enum: Enumerations +# Enum: Enumerations Enumerations are used to define sets of integer values and for defining types for such sets of values. There are two kinds of enumerations, "plain" `enum`s and `class enum`s. Enumeration rule summary: -* [Enum.1: Prefer enumerations over macros](#Renum-macro) -* [Enum.2: Use enumerations to represent sets of related named constants](#Renum-set) -* [Enum.3: Prefer `enum class`es over "plain" `enum`s](#Renum-class) -* [Enum.4: Define operations on enumerations for safe and simple use](#Renum-oper) -* [Enum.5: Don't use `ALL_CAPS` for enumerators](#Renum-caps) -* [Enum.6: Avoid unnamed enumerations](#Renum-unnamed) -* [Enum.7: Specify the underlying type of an enumeration only when necessary](#Renum-underlying) -* [Enum.8: Specify enumerator values only when necessary](#Renum-value) +* [Enum.1: Prefer enumerations over macros](#renum-macro) +* [Enum.2: Use enumerations to represent sets of related named constants](#renum-set) +* [Enum.3: Prefer `enum class`es over "plain" `enum`s](#renum-class) +* [Enum.4: Define operations on enumerations for safe and simple use](#renum-oper) +* [Enum.5: Don't use `ALL_CAPS` for enumerators](#renum-caps) +* [Enum.6: Avoid unnamed enumerations](#renum-unnamed) +* [Enum.7: Specify the underlying type of an enumeration only when necessary](#renum-underlying) +* [Enum.8: Specify enumerator values only when necessary](#renum-value) -### Enum.1: Prefer enumerations over macros +### Enum.1: Prefer enumerations over macros ##### Reason @@ -9098,7 +9098,7 @@ Also consider `constexpr` and `const inline` variables. Flag macros that define integer values. Use `enum` or `const inline` or another non-macro alternative instead. -### Enum.2: Use enumerations to represent sets of related named constants +### Enum.2: Use enumerations to represent sets of related named constants ##### Reason @@ -9133,7 +9133,7 @@ Such off-by-one `switch`-statements are often the results of an added enumerator * Flag `switch`-statements where the `case`s cover a few enumerators of an enumeration, but there is no `default`. -### Enum.3: Prefer class enums over "plain" enums +### Enum.3: Prefer class enums over "plain" enums ##### Reason @@ -9167,7 +9167,7 @@ Instead use an `enum class`: (Simple) Warn on any non-class `enum` definition. -### Enum.4: Define operations on enumerations for safe and simple use +### Enum.4: Define operations on enumerations for safe and simple use ##### Reason @@ -9200,7 +9200,7 @@ is an infinite recursion, and writing it without a cast, using a `switch` on all Flag repeated expressions cast back into an enumeration. -### Enum.5: Don't use `ALL_CAPS` for enumerators +### Enum.5: Don't use `ALL_CAPS` for enumerators ##### Reason @@ -9222,7 +9222,7 @@ Avoid clashes with macros. Flag ALL_CAPS enumerators. -### Enum.6: Avoid unnamed enumerations +### Enum.6: Avoid unnamed enumerations ##### Reason @@ -9247,7 +9247,7 @@ Use `constexpr` values instead. For example: Flag unnamed enumerations. -### Enum.7: Specify the underlying type of an enumeration only when necessary +### Enum.7: Specify the underlying type of an enumeration only when necessary ##### Reason @@ -9285,7 +9285,7 @@ or to ensure that values of that type have a specified bit-precision: ???? -### Enum.8: Specify enumerator values only when necessary +### Enum.8: Specify enumerator values only when necessary ##### Reason @@ -9310,7 +9310,7 @@ and where consecutive values are undesirable (e.g., to get separate bits as in ` * Flag explicitly specified all-consecutive enumerator values -# R: Resource management +# R: Resource management This section contains rules related to resources. A resource is anything that must be acquired and (explicitly or implicitly) released, such as memory, file handles, sockets, and locks. @@ -9325,39 +9325,39 @@ Here, we ignore such cases. * Resource management rule summary: - * [R.1: Manage resources automatically using resource handles and RAII (Resource Acquisition Is Initialization)](#Rr-raii) - * [R.2: In interfaces, use raw pointers to denote individual objects (only)](#Rr-use-ptr) - * [R.3: A raw pointer (a `T*`) is non-owning](#Rr-ptr) - * [R.4: A raw reference (a `T&`) is non-owning](#Rr-ref) - * [R.5: Prefer scoped objects, don't heap-allocate unnecessarily](#Rr-scoped) - * [R.6: Avoid non-`const` global variables](#Rr-global) + * [R.1: Manage resources automatically using resource handles and RAII (Resource Acquisition Is Initialization)](#rr-raii) + * [R.2: In interfaces, use raw pointers to denote individual objects (only)](#rr-use-ptr) + * [R.3: A raw pointer (a `T*`) is non-owning](#rr-ptr) + * [R.4: A raw reference (a `T&`) is non-owning](#rr-ref) + * [R.5: Prefer scoped objects, don't heap-allocate unnecessarily](#rr-scoped) + * [R.6: Avoid non-`const` global variables](#rr-global) * Allocation and deallocation rule summary: - * [R.10: Avoid `malloc()` and `free()`](#Rr-mallocfree) - * [R.11: Avoid calling `new` and `delete` explicitly](#Rr-newdelete) - * [R.12: Immediately give the result of an explicit resource allocation to a manager object](#Rr-immediate-alloc) - * [R.13: Perform at most one explicit resource allocation in a single expression statement](#Rr-single-alloc) - * [R.14: Avoid `[]` parameters, prefer `span`](#Rr-ap) - * [R.15: Always overload matched allocation/deallocation pairs](#Rr-pair) + * [R.10: Avoid `malloc()` and `free()`](#rr-mallocfree) + * [R.11: Avoid calling `new` and `delete` explicitly](#rr-newdelete) + * [R.12: Immediately give the result of an explicit resource allocation to a manager object](#rr-immediate-alloc) + * [R.13: Perform at most one explicit resource allocation in a single expression statement](#rr-single-alloc) + * [R.14: Avoid `[]` parameters, prefer `span`](#rr-ap) + * [R.15: Always overload matched allocation/deallocation pairs](#rr-pair) -* Smart pointer rule summary: +* Smart pointer rule summary: - * [R.20: Use `unique_ptr` or `shared_ptr` to represent ownership](#Rr-owner) - * [R.21: Prefer `unique_ptr` over `shared_ptr` unless you need to share ownership](#Rr-unique) - * [R.22: Use `make_shared()` to make `shared_ptr`s](#Rr-make_shared) - * [R.23: Use `make_unique()` to make `unique_ptr`s](#Rr-make_unique) - * [R.24: Use `std::weak_ptr` to break cycles of `shared_ptr`s](#Rr-weak_ptr) - * [R.30: Take smart pointers as parameters only to explicitly express lifetime semantics](#Rr-smartptrparam) - * [R.31: If you have non-`std` smart pointers, follow the basic pattern from `std`](#Rr-smart) - * [R.32: Take a `unique_ptr` parameter to express that a function assumes ownership of a `widget`](#Rr-uniqueptrparam) - * [R.33: Take a `unique_ptr&` parameter to express that a function reseats the `widget`](#Rr-reseat) - * [R.34: Take a `shared_ptr` parameter to express shared ownership](#Rr-sharedptrparam-owner) - * [R.35: Take a `shared_ptr&` parameter to express that a function might reseat the shared pointer](#Rr-sharedptrparam) - * [R.36: Take a `const shared_ptr&` parameter to express that it might retain a reference count to the object ???](#Rr-sharedptrparam-const) - * [R.37: Do not pass a pointer or reference obtained from an aliased smart pointer](#Rr-smartptrget) + * [R.20: Use `unique_ptr` or `shared_ptr` to represent ownership](#rr-owner) + * [R.21: Prefer `unique_ptr` over `shared_ptr` unless you need to share ownership](#rr-unique) + * [R.22: Use `make_shared()` to make `shared_ptr`s](#rr-make_shared) + * [R.23: Use `make_unique()` to make `unique_ptr`s](#rr-make_unique) + * [R.24: Use `std::weak_ptr` to break cycles of `shared_ptr`s](#rr-weak_ptr) + * [R.30: Take smart pointers as parameters only to explicitly express lifetime semantics](#rr-smartptrparam) + * [R.31: If you have non-`std` smart pointers, follow the basic pattern from `std`](#rr-smart) + * [R.32: Take a `unique_ptr` parameter to express that a function assumes ownership of a `widget`](#rr-uniqueptrparam) + * [R.33: Take a `unique_ptr&` parameter to express that a function reseats the `widget`](#rr-reseat) + * [R.34: Take a `shared_ptr` parameter to express shared ownership](#rr-sharedptrparam-owner) + * [R.35: Take a `shared_ptr&` parameter to express that a function might reseat the shared pointer](#rr-sharedptrparam) + * [R.36: Take a `const shared_ptr&` parameter to express that it might retain a reference count to the object ???](#rr-sharedptrparam-const) + * [R.37: Do not pass a pointer or reference obtained from an aliased smart pointer](#rr-smartptrget) -### R.1: Manage resources automatically using resource handles and RAII (Resource Acquisition Is Initialization) +### R.1: Manage resources automatically using resource handles and RAII (Resource Acquisition Is Initialization) ##### Reason @@ -9415,11 +9415,11 @@ What is `Port`? A handy wrapper that encapsulates the resource: ##### Note -Where a resource is "ill-behaved" in that it isn't represented as a class with a destructor, wrap it in a class or use [`finally`](#Re-finally) +Where a resource is "ill-behaved" in that it isn't represented as a class with a destructor, wrap it in a class or use [`finally`](#re-finally) -**See also**: [RAII](#Re-raii) +**See also**: [RAII](#re-raii) -### R.2: In interfaces, use raw pointers to denote individual objects (only) +### R.2: In interfaces, use raw pointers to denote individual objects (only) ##### Reason @@ -9461,7 +9461,7 @@ However, where `nullptr` is a possible value, a reference might not be a reasona This rule would generate a huge number of false positives if applied to an older code base. * Flag array names passed as simple pointers -### R.3: A raw pointer (a `T*`) is non-owning +### R.3: A raw pointer (a `T*`) is non-owning ##### Reason @@ -9541,7 +9541,7 @@ Returning a (raw) pointer imposes a lifetime management uncertainty on the calle delete p; } -In addition to suffering from the problem of [leak](#Rp-leak), this adds a spurious allocation and deallocation operation, and is needlessly verbose. If Gadget is cheap to move out of a function (i.e., is small or has an efficient move operation), just return it "by value" (see ["out" return values](#Rf-out)): +In addition to suffering from the problem of [leak](#rp-leak), this adds a spurious allocation and deallocation operation, and is needlessly verbose. If Gadget is cheap to move out of a function (i.e., is small or has an efficient move operation), just return it "by value" (see ["out" return values](#rf-out)): Gadget make_gadget(int n) { @@ -9566,7 +9566,7 @@ If pointer semantics are required (e.g., because the return type needs to refer * (Simple) Warn if a function returns an object that was allocated within the function but has a move constructor. Suggest considering returning it by value instead. -### R.4: A raw reference (a `T&`) is non-owning +### R.4: A raw reference (a `T&`) is non-owning ##### Reason @@ -9582,13 +9582,13 @@ We want owners identified so that we can reliably and efficiently delete the obj delete &r; // bad: violated the rule against deleting raw pointers } -**See also**: [The raw pointer rule](#Rr-ptr) +**See also**: [The raw pointer rule](#rr-ptr) ##### Enforcement -See [the raw pointer rule](#Rr-ptr) +See [the raw pointer rule](#rr-ptr) -### R.5: Prefer scoped objects, don't heap-allocate unnecessarily +### R.5: Prefer scoped objects, don't heap-allocate unnecessarily ##### Reason @@ -9625,13 +9625,13 @@ Exception: Do not produce such a warning on a local `Unique_pointer` to an unbou If your stack space is limited, it is OK to create a local `const unique_ptr` to store the object on the heap instead of the stack. -### R.6: Avoid non-`const` global variables +### R.6: Avoid non-`const` global variables -See [I.2](#Ri-global) +See [I.2](#ri-global) -## R.alloc: Allocation and deallocation +## R.alloc: Allocation and deallocation -### R.10: Avoid `malloc()` and `free()` +### R.10: Avoid `malloc()` and `free()` ##### Reason @@ -9678,7 +9678,7 @@ In such cases, consider the `nothrow` versions of `new`. Flag explicit use of `malloc` and `free`. -### R.11: Avoid calling `new` and `delete` explicitly +### R.11: Avoid calling `new` and `delete` explicitly ##### Reason @@ -9696,7 +9696,7 @@ If you have a naked `new`, you probably need a naked `delete` somewhere, so you (Simple) Warn on any explicit use of `new` and `delete`. Suggest using `make_unique` instead. -### R.12: Immediately give the result of an explicit resource allocation to a manager object +### R.12: Immediately give the result of an explicit resource allocation to a manager object ##### Reason @@ -9729,7 +9729,7 @@ The use of the file handle (in `ifstream`) is simple, efficient, and safe. * Flag explicit allocations used to initialize pointers (problem: how many direct resource allocations can we recognize?) -### R.13: Perform at most one explicit resource allocation in a single expression statement +### R.13: Perform at most one explicit resource allocation in a single expression statement ##### Reason @@ -9765,7 +9765,7 @@ Write your own factory wrapper if there is not one already. * Flag expressions with multiple explicit resource allocations (problem: how many direct resource allocations can we recognize?) -### R.14: Avoid `[]` parameters, prefer `span` +### R.14: Avoid `[]` parameters, prefer `span` ##### Reason @@ -9785,7 +9785,7 @@ Use `span` to preserve size information. Flag `[]` parameters. Use `span` instead. -### R.15: Always overload matched allocation/deallocation pairs +### R.15: Always overload matched allocation/deallocation pairs ##### Reason @@ -9809,9 +9809,9 @@ Don't leave it undeclared. Flag incomplete pairs. -## R.smart: Smart pointers +## R.smart: Smart pointers -### R.20: Use `unique_ptr` or `shared_ptr` to represent ownership +### R.20: Use `unique_ptr` or `shared_ptr` to represent ownership ##### Reason @@ -9835,7 +9835,7 @@ This will leak the object used to initialize `p1` (only). * (Simple) Warn if the return value of `new` is assigned to a raw pointer. * (Simple) Warn if the result of a function returning a raw owning pointer is assigned to a raw pointer. -### R.21: Prefer `unique_ptr` over `shared_ptr` unless you need to share ownership +### R.21: Prefer `unique_ptr` over `shared_ptr` unless you need to share ownership ##### Reason @@ -9865,7 +9865,7 @@ This is more efficient: (Simple) Warn if a function uses a `Shared_pointer` with an object allocated within the function, but never returns the `Shared_pointer` or passes it to a function requiring a `Shared_pointer`. Suggest using `unique_ptr` instead. -### R.22: Use `make_shared()` to make `shared_ptr`s +### R.22: Use `make_shared()` to make `shared_ptr`s ##### Reason @@ -9886,7 +9886,7 @@ The `make_shared()` version mentions `X` only once, so it is usually shorter (as (Simple) Warn if a `shared_ptr` is constructed from the result of `new` rather than `make_shared`. -### R.23: Use `make_unique()` to make `unique_ptr`s +### R.23: Use `make_unique()` to make `unique_ptr`s ##### Reason @@ -9903,7 +9903,7 @@ It also ensures exception safety in complex expressions (in pre-C++17 code). (Simple) Warn if a `unique_ptr` is constructed from the result of `new` rather than `make_unique`. -### R.24: Use `std::weak_ptr` to break cycles of `shared_ptr`s +### R.24: Use `std::weak_ptr` to break cycles of `shared_ptr`s ##### Reason @@ -9950,11 +9950,11 @@ You could "temporarily share ownership" simply by using another `shared_ptr`.) ??? probably impossible. If we could statically detect cycles, we wouldn't need `weak_ptr` -### R.30: Take smart pointers as parameters only to explicitly express lifetime semantics +### R.30: Take smart pointers as parameters only to explicitly express lifetime semantics -See [F.7](#Rf-smart). +See [F.7](#rf-smart). -### R.31: If you have non-`std` smart pointers, follow the basic pattern from `std` +### R.31: If you have non-`std` smart pointers, follow the basic pattern from `std` ##### Reason @@ -9982,12 +9982,12 @@ Any type (including primary template or specialization) that overloads unary `*` p->foo(); } -Both cases are an error under the [`sharedptrparam` guideline](#Rr-smartptrparam): +Both cases are an error under the [`sharedptrparam` guideline](#rr-smartptrparam): `p` is a `Shared_pointer`, but nothing about its sharedness is used here and passing it by value is a silent pessimization; these functions should accept a smart pointer only if they need to participate in the widget's lifetime management. Otherwise they should accept a `widget*`, if it can be `nullptr`. Otherwise, and ideally, the function should accept a `widget&`. These smart pointers match the `Shared_pointer` concept, so these guideline enforcement rules work on them out of the box and expose this common pessimization. -### R.32: Take a `unique_ptr` parameter to express that a function assumes ownership of a `widget` +### R.32: Take a `unique_ptr` parameter to express that a function assumes ownership of a `widget` ##### Reason @@ -10003,7 +10003,7 @@ Using `unique_ptr` in this way both documents and enforces the function call's o * (Simple) Warn if a function takes a `Unique_pointer` parameter by lvalue reference and does not either assign to it or call `reset()` on it on at least one code path. Suggest taking a `T*` or `T&` instead. -### R.33: Take a `unique_ptr&` parameter to express that a function reseats the `widget` +### R.33: Take a `unique_ptr&` parameter to express that a function reseats the `widget` ##### Reason @@ -10021,7 +10021,7 @@ Using `unique_ptr` in this way both documents and enforces the function call's r * (Simple) Warn if a function takes a `Unique_pointer` parameter by lvalue reference and does not either assign to it or call `reset()` on it on at least one code path. Suggest taking a `T*` or `T&` instead. -### R.34: Take a `shared_ptr` parameter to express shared ownership +### R.34: Take a `shared_ptr` parameter to express shared ownership ##### Reason @@ -10046,7 +10046,7 @@ This makes the function's ownership sharing explicit. * (Simple) ((Foundation)) Warn if a function takes a `Shared_pointer` by value or by reference to `const` and does not copy or move it to another `Shared_pointer` on at least one code path. Suggest taking a `T*` or `T&` instead. * (Simple) ((Foundation)) Warn if a function takes a `Shared_pointer` by rvalue reference. Suggesting taking it by value instead. -### R.35: Take a `shared_ptr&` parameter to express that a function might reseat the shared pointer +### R.35: Take a `shared_ptr&` parameter to express that a function might reseat the shared pointer ##### Reason @@ -10070,7 +10070,7 @@ This makes the function's reseating explicit. * (Simple) ((Foundation)) Warn if a function takes a `Shared_pointer` by value or by reference to `const` and does not copy or move it to another `Shared_pointer` on at least one code path. Suggest taking a `T*` or `T&` instead. * (Simple) ((Foundation)) Warn if a function takes a `Shared_pointer` by rvalue reference. Suggesting taking it by value instead. -### R.36: Take a `const shared_ptr&` parameter to express that it might retain a reference count to the object ??? +### R.36: Take a `const shared_ptr&` parameter to express that it might retain a reference count to the object ??? ##### Reason @@ -10090,7 +10090,7 @@ This makes the function's ??? explicit. * (Simple) ((Foundation)) Warn if a function takes a `Shared_pointer` by value or by reference to `const` and does not copy or move it to another `Shared_pointer` on at least one code path. Suggest taking a `T*` or `T&` instead. * (Simple) ((Foundation)) Warn if a function takes a `Shared_pointer` by rvalue reference. Suggesting taking it by value instead. -### R.37: Do not pass a pointer or reference obtained from an aliased smart pointer +### R.37: Do not pass a pointer or reference obtained from an aliased smart pointer ##### Reason @@ -10151,94 +10151,94 @@ The fix is simple -- take a local copy of the pointer to "keep a ref count" for * (Simple) Warn if a pointer or reference obtained from a smart pointer variable (`Unique_pointer` or `Shared_pointer`) that is non-local, or that is local but potentially aliased, is used in a function call. If the smart pointer is a `Shared_pointer` then suggest taking a local copy of the smart pointer and obtain a pointer or reference from that instead. -# ES: Expressions and statements +# ES: Expressions and statements Expressions and statements are the lowest and most direct way of expressing actions and computation. Declarations in local scopes are statements. -For naming, commenting, and indentation rules, see [NL: Naming and layout](#S-naming). +For naming, commenting, and indentation rules, see [NL: Naming and layout](#s-naming). General rules: -* [ES.1: Prefer the standard library to other libraries and to "handcrafted code"](#Res-lib) -* [ES.2: Prefer suitable abstractions to direct use of language features](#Res-abstr) -* [ES.3: Don't repeat yourself, avoid redundant code](#Res-DRY) +* [ES.1: Prefer the standard library to other libraries and to "handcrafted code"](#res-lib) +* [ES.2: Prefer suitable abstractions to direct use of language features](#res-abstr) +* [ES.3: Don't repeat yourself, avoid redundant code](#res-dry) Declaration rules: -* [ES.5: Keep scopes small](#Res-scope) -* [ES.6: Declare names in for-statement initializers and conditions to limit scope](#Res-cond) -* [ES.7: Keep common and local names short, and keep uncommon and non-local names longer](#Res-name-length) -* [ES.8: Avoid similar-looking names](#Res-name-similar) -* [ES.9: Avoid `ALL_CAPS` names](#Res-not-CAPS) -* [ES.10: Declare one name (only) per declaration](#Res-name-one) -* [ES.11: Use `auto` to avoid redundant repetition of type names](#Res-auto) -* [ES.12: Do not reuse names in nested scopes](#Res-reuse) -* [ES.20: Always initialize an object](#Res-always) -* [ES.21: Don't introduce a variable (or constant) before you need to use it](#Res-introduce) -* [ES.22: Don't declare a variable until you have a value to initialize it with](#Res-init) -* [ES.23: Prefer the `{}`-initializer syntax](#Res-list) -* [ES.24: Use a `unique_ptr` to hold pointers](#Res-unique) -* [ES.25: Declare an object `const` or `constexpr` unless you want to modify its value later on](#Res-const) -* [ES.26: Don't use a variable for two unrelated purposes](#Res-recycle) -* [ES.27: Use `std::array` or `stack_array` for arrays on the stack](#Res-stack) -* [ES.28: Use lambdas for complex initialization, especially of `const` variables](#Res-lambda-init) -* [ES.30: Don't use macros for program text manipulation](#Res-macros) -* [ES.31: Don't use macros for constants or "functions"](#Res-macros2) -* [ES.32: Use `ALL_CAPS` for all macro names](#Res-ALL_CAPS) -* [ES.33: If you must use macros, give them unique names](#Res-MACROS) -* [ES.34: Don't define a (C-style) variadic function](#Res-ellipses) +* [ES.5: Keep scopes small](#res-scope) +* [ES.6: Declare names in for-statement initializers and conditions to limit scope](#res-cond) +* [ES.7: Keep common and local names short, and keep uncommon and non-local names longer](#res-name-length) +* [ES.8: Avoid similar-looking names](#res-name-similar) +* [ES.9: Avoid `ALL_CAPS` names](#res-not-caps) +* [ES.10: Declare one name (only) per declaration](#res-name-one) +* [ES.11: Use `auto` to avoid redundant repetition of type names](#res-auto) +* [ES.12: Do not reuse names in nested scopes](#res-reuse) +* [ES.20: Always initialize an object](#res-always) +* [ES.21: Don't introduce a variable (or constant) before you need to use it](#res-introduce) +* [ES.22: Don't declare a variable until you have a value to initialize it with](#res-init) +* [ES.23: Prefer the `{}`-initializer syntax](#res-list) +* [ES.24: Use a `unique_ptr` to hold pointers](#res-unique) +* [ES.25: Declare an object `const` or `constexpr` unless you want to modify its value later on](#res-const) +* [ES.26: Don't use a variable for two unrelated purposes](#res-recycle) +* [ES.27: Use `std::array` or `stack_array` for arrays on the stack](#res-stack) +* [ES.28: Use lambdas for complex initialization, especially of `const` variables](#res-lambda-init) +* [ES.30: Don't use macros for program text manipulation](#res-macros) +* [ES.31: Don't use macros for constants or "functions"](#res-macros2) +* [ES.32: Use `ALL_CAPS` for all macro names](#res-all_caps) +* [ES.33: If you must use macros, give them unique names](#res-macros3) +* [ES.34: Don't define a (C-style) variadic function](#res-ellipses) Expression rules: -* [ES.40: Avoid complicated expressions](#Res-complicated) -* [ES.41: If in doubt about operator precedence, parenthesize](#Res-parens) -* [ES.42: Keep use of pointers simple and straightforward](#Res-ptr) -* [ES.43: Avoid expressions with undefined order of evaluation](#Res-order) -* [ES.44: Don't depend on order of evaluation of function arguments](#Res-order-fct) -* [ES.45: Avoid "magic constants"; use symbolic constants](#Res-magic) -* [ES.46: Avoid narrowing conversions](#Res-narrowing) -* [ES.47: Use `nullptr` rather than `0` or `NULL`](#Res-nullptr) -* [ES.48: Avoid casts](#Res-casts) -* [ES.49: If you must use a cast, use a named cast](#Res-casts-named) -* [ES.50: Don't cast away `const`](#Res-casts-const) -* [ES.55: Avoid the need for range checking](#Res-range-checking) -* [ES.56: Write `std::move()` only when you need to explicitly move an object to another scope](#Res-move) -* [ES.60: Avoid `new` and `delete` outside resource management functions](#Res-new) -* [ES.61: Delete arrays using `delete[]` and non-arrays using `delete`](#Res-del) -* [ES.62: Don't compare pointers into different arrays](#Res-arr2) -* [ES.63: Don't slice](#Res-slice) -* [ES.64: Use the `T{e}`notation for construction](#Res-construct) -* [ES.65: Don't dereference an invalid pointer](#Res-deref) +* [ES.40: Avoid complicated expressions](#res-complicated) +* [ES.41: If in doubt about operator precedence, parenthesize](#res-parens) +* [ES.42: Keep use of pointers simple and straightforward](#res-ptr) +* [ES.43: Avoid expressions with undefined order of evaluation](#res-order) +* [ES.44: Don't depend on order of evaluation of function arguments](#res-order-fct) +* [ES.45: Avoid "magic constants"; use symbolic constants](#res-magic) +* [ES.46: Avoid narrowing conversions](#res-narrowing) +* [ES.47: Use `nullptr` rather than `0` or `NULL`](#res-nullptr) +* [ES.48: Avoid casts](#res-casts) +* [ES.49: If you must use a cast, use a named cast](#res-casts-named) +* [ES.50: Don't cast away `const`](#res-casts-const) +* [ES.55: Avoid the need for range checking](#res-range-checking) +* [ES.56: Write `std::move()` only when you need to explicitly move an object to another scope](#res-move) +* [ES.60: Avoid `new` and `delete` outside resource management functions](#res-new) +* [ES.61: Delete arrays using `delete[]` and non-arrays using `delete`](#res-del) +* [ES.62: Don't compare pointers into different arrays](#res-arr2) +* [ES.63: Don't slice](#res-slice) +* [ES.64: Use the `T{e}`notation for construction](#res-construct) +* [ES.65: Don't dereference an invalid pointer](#res-deref) Statement rules: -* [ES.70: Prefer a `switch`-statement to an `if`-statement when there is a choice](#Res-switch-if) -* [ES.71: Prefer a range-`for`-statement to a `for`-statement when there is a choice](#Res-for-range) -* [ES.72: Prefer a `for`-statement to a `while`-statement when there is an obvious loop variable](#Res-for-while) -* [ES.73: Prefer a `while`-statement to a `for`-statement when there is no obvious loop variable](#Res-while-for) -* [ES.74: Prefer to declare a loop variable in the initializer part of a `for`-statement](#Res-for-init) -* [ES.75: Avoid `do`-statements](#Res-do) -* [ES.76: Avoid `goto`](#Res-goto) -* [ES.77: Minimize the use of `break` and `continue` in loops](#Res-continue) -* [ES.78: Don't rely on implicit fallthrough in `switch` statements](#Res-break) -* [ES.79: Use `default` to handle common cases (only)](#Res-default) -* [ES.84: Don't try to declare a local variable with no name](#Res-noname) -* [ES.85: Make empty statements visible](#Res-empty) -* [ES.86: Avoid modifying loop control variables inside the body of raw for-loops](#Res-loop-counter) -* [ES.87: Don't add redundant `==` or `!=` to conditions](#Res-if) +* [ES.70: Prefer a `switch`-statement to an `if`-statement when there is a choice](#res-switch-if) +* [ES.71: Prefer a range-`for`-statement to a `for`-statement when there is a choice](#res-for-range) +* [ES.72: Prefer a `for`-statement to a `while`-statement when there is an obvious loop variable](#res-for-while) +* [ES.73: Prefer a `while`-statement to a `for`-statement when there is no obvious loop variable](#res-while-for) +* [ES.74: Prefer to declare a loop variable in the initializer part of a `for`-statement](#res-for-init) +* [ES.75: Avoid `do`-statements](#res-do) +* [ES.76: Avoid `goto`](#res-goto) +* [ES.77: Minimize the use of `break` and `continue` in loops](#res-continue) +* [ES.78: Don't rely on implicit fallthrough in `switch` statements](#res-break) +* [ES.79: Use `default` to handle common cases (only)](#res-default) +* [ES.84: Don't try to declare a local variable with no name](#res-noname) +* [ES.85: Make empty statements visible](#res-empty) +* [ES.86: Avoid modifying loop control variables inside the body of raw for-loops](#res-loop-counter) +* [ES.87: Don't add redundant `==` or `!=` to conditions](#res-if) Arithmetic rules: -* [ES.100: Don't mix signed and unsigned arithmetic](#Res-mix) -* [ES.101: Use unsigned types for bit manipulation](#Res-unsigned) -* [ES.102: Use signed types for arithmetic](#Res-signed) -* [ES.103: Don't overflow](#Res-overflow) -* [ES.104: Don't underflow](#Res-underflow) -* [ES.105: Don't divide by integer zero](#Res-zero) -* [ES.106: Don't try to avoid negative values by using `unsigned`](#Res-nonnegative) -* [ES.107: Don't use `unsigned` for subscripts, prefer `gsl::index`](#Res-subscripts) +* [ES.100: Don't mix signed and unsigned arithmetic](#res-mix) +* [ES.101: Use unsigned types for bit manipulation](#res-unsigned) +* [ES.102: Use signed types for arithmetic](#res-signed) +* [ES.103: Don't overflow](#res-overflow) +* [ES.104: Don't underflow](#res-underflow) +* [ES.105: Don't divide by integer zero](#res-zero) +* [ES.106: Don't try to avoid negative values by using `unsigned`](#res-nonnegative) +* [ES.107: Don't use `unsigned` for subscripts, prefer `gsl::index`](#res-subscripts) -### ES.1: Prefer the standard library to other libraries and to "handcrafted code" +### ES.1: Prefer the standard library to other libraries and to "handcrafted code" ##### Reason @@ -10269,7 +10269,7 @@ Large parts of the standard library rely on dynamic allocation (free store). The Not easy. ??? Look for messy loops, nested loops, long functions, absence of function calls, lack of use of built-in types. Cyclomatic complexity? -### ES.2: Prefer suitable abstractions to direct use of language features +### ES.2: Prefer suitable abstractions to direct use of language features ##### Reason @@ -10306,13 +10306,13 @@ Once the checking for overflow and error handling has been added that code gets Not easy. ??? Look for messy loops, nested loops, long functions, absence of function calls, lack of use of built-in types. Cyclomatic complexity? -### ES.3: Don't repeat yourself, avoid redundant code +### ES.3: Don't repeat yourself, avoid redundant code Duplicated or otherwise redundant code obscures intent, makes it harder to understand the logic, and makes maintenance harder, among other problems. It often arises from cut-and-paste programming. Use standard algorithms where appropriate, instead of writing some own implementation. -**See also**: [SL.1](#Rsl-lib), [ES.11](#Res-auto) +**See also**: [SL.1](#rsl-lib), [ES.11](#res-auto) ##### Example @@ -10348,7 +10348,7 @@ Use standard algorithms where appropriate, instead of writing some own implement A declaration is a statement. A declaration introduces a name into a scope and might cause the construction of a named object. -### ES.5: Keep scopes small +### ES.5: Keep scopes small ##### Reason @@ -10408,7 +10408,7 @@ In this case, it might be a good idea to factor out the read: * Flag loop variable declared outside a loop and not used after the loop * Flag when expensive resources, such as file handles and locks are not used for N-lines (for some suitable N) -### ES.6: Declare names in for-statement initializers and conditions to limit scope +### ES.6: Declare names in for-statement initializers and conditions to limit scope ##### Reason @@ -10444,7 +10444,7 @@ Minimize resource retention. } // j is still visible here and isn't needed -**See also**: [Don't use a variable for two unrelated purposes](#Res-recycle) +**See also**: [Don't use a variable for two unrelated purposes](#res-recycle) ##### Enforcement @@ -10471,7 +10471,7 @@ Note: C++17 and C++20 also add `if`, `switch`, and range-`for` initializer state * Flag selection/loop variables declared before the body and not used after the body * (hard) Flag selection/loop variables declared before the body and used after the body for an unrelated purpose. -### ES.7: Keep common and local names short, and keep uncommon and non-local names longer +### ES.7: Keep common and local names short, and keep uncommon and non-local names longer ##### Reason @@ -10541,7 +10541,7 @@ We recommend keeping functions short, but that rule isn't universally adhered to Check length of local and non-local names. Also take function length into account. -### ES.8: Avoid similar-looking names +### ES.8: Avoid similar-looking names ##### Reason @@ -10568,7 +10568,7 @@ Antique header files might declare non-types and types with the same name in the * Check names against a list of known confusing letter and digit combinations. * Flag a declaration of a variable, function, or enumerator that hides a class or enumeration declared in the same scope. -### ES.9: Avoid `ALL_CAPS` names +### ES.9: Avoid `ALL_CAPS` names ##### Reason @@ -10597,9 +10597,9 @@ Do not use `ALL_CAPS` for constants just because constants used to be macros. ##### Enforcement -Flag all uses of ALL CAPS. For older code, accept ALL CAPS for macro names and flag all non-ALL-CAPS macro names. +Flag all uses of ALL CAPS. For older code, accept ALL CAPS for macro names and flag all non-all-CAPS macro names. -### ES.10: Declare one name (only) per declaration +### ES.10: Declare one name (only) per declaration ##### Reason @@ -10657,7 +10657,7 @@ In a long list of declarators it is easy to overlook an uninitialized variable. Flag variable and constant declarations with multiple declarators (e.g., `int* p, q;`) -### ES.11: Use `auto` to avoid redundant repetition of type names +### ES.11: Use `auto` to avoid redundant repetition of type names ##### Reason @@ -10710,7 +10710,7 @@ As of C++20, we can (and should) use concepts to be more specific about the type Flag redundant repetition of type names in a declaration. -### ES.12: Do not reuse names in nested scopes +### ES.12: Do not reuse names in nested scopes ##### Reason @@ -10803,7 +10803,7 @@ For example, had we forgotten the using declaration, a call `d.f(1)` would not h * Flag reuse of a global name as a local variable or a member name * Flag reuse of a base class member name in a derived class (except for function names) -### ES.20: Always initialize an object +### ES.20: Always initialize an object ##### Reason @@ -10872,7 +10872,7 @@ Assuming that there is a logical connection between `i` and `j`, that connection auto [i, j] = make_related_widgets(cond); // C++17 If the `make_related_widgets` function is otherwise redundant, -we can eliminate it by using a lambda [ES.28](#Res-lambda-init): +we can eliminate it by using a lambda [ES.28](#res-lambda-init): auto [i, j] = [x] { return (x) ? pair{f1(), f2()} : pair{f3(), f4()} }(); // C++17 @@ -10982,7 +10982,7 @@ or maybe: return p.second; }(); -**See also**: [ES.28](#Res-lambda-init) +**See also**: [ES.28](#res-lambda-init) ##### Enforcement @@ -10991,7 +10991,7 @@ or maybe: * Check that an uninitialized buffer is written into *immediately* after declaration. Passing an uninitialized variable as a reference to non-`const` argument can be assumed to be a write into the variable. -### ES.21: Don't introduce a variable (or constant) before you need to use it +### ES.21: Don't introduce a variable (or constant) before you need to use it ##### Reason @@ -11007,7 +11007,7 @@ Readability. To limit the scope in which the variable can be used. Flag declarations that are distant from their first use. -### ES.22: Don't declare a variable until you have a value to initialize it with +### ES.22: Don't declare a variable until you have a value to initialize it with ##### Reason @@ -11040,14 +11040,14 @@ This would be fine if there was a default initialization for `SomeLargeType` tha Otherwise, a programmer might very well wonder if every possible path through the maze of conditions has been covered. If not, we have a "use before set" bug. This is a maintenance trap. -For initializers of moderate complexity, including for `const` variables, consider using a lambda to express the initializer; see [ES.28](#Res-lambda-init). +For initializers of moderate complexity, including for `const` variables, consider using a lambda to express the initializer; see [ES.28](#res-lambda-init). ##### Enforcement * Flag declarations with default initialization that are assigned to before they are first read. * Flag any complicated computation after an uninitialized variable and before its use. -### ES.23: Prefer the `{}`-initializer syntax +### ES.23: Prefer the `{}`-initializer syntax ##### Reason @@ -11149,7 +11149,7 @@ Use plain `{}`-initialization unless you specifically want to disable explicit c * Flag uses of `=` to initialize arithmetic types where narrowing occurs. * Flag uses of `()` initialization syntax that are actually declarations. (Many compilers should warn on this already.) -### ES.24: Use a `unique_ptr` to hold pointers +### ES.24: Use a `unique_ptr` to hold pointers ##### Reason @@ -11179,7 +11179,7 @@ The same is the case when `at()` throws. In both cases, the `delete p2` statemen Look for raw pointers that are targets of `new`, `malloc()`, or functions that might return such pointers. -### ES.25: Declare an object `const` or `constexpr` unless you want to modify its value later on +### ES.25: Declare an object `const` or `constexpr` unless you want to modify its value later on ##### Reason @@ -11200,7 +11200,7 @@ Look to see if a variable is actually mutated, and flag it if not. Unfortunately, it might be impossible to detect when a non-`const` was not *intended* to vary (vs when it merely did not vary). -### ES.26: Don't use a variable for two unrelated purposes +### ES.26: Don't use a variable for two unrelated purposes ##### Reason @@ -11239,7 +11239,7 @@ As an optimization, you might want to reuse a buffer as a scratch pad, but even Flag recycled variables. -### ES.27: Use `std::array` or `stack_array` for arrays on the stack +### ES.27: Use `std::array` or `stack_array` for arrays on the stack ##### Reason @@ -11283,7 +11283,7 @@ The definition of `a2` is C but not C++ and is considered a security risk. * Flag arrays with non-constant bounds (C-style VLAs) * Flag arrays with non-local constant bounds -### ES.28: Use lambdas for complex initialization, especially of `const` variables +### ES.28: Use lambdas for complex initialization, especially of `const` variables ##### Reason @@ -11313,7 +11313,7 @@ If at all possible, reduce the conditions to a simple set of alternatives (e.g., Hard. At best a heuristic. Look for an uninitialized variable followed by a loop assigning to it. -### ES.30: Don't use macros for program text manipulation +### ES.30: Don't use macros for program text manipulation ##### Reason @@ -11380,7 +11380,7 @@ In the future, static reflection is likely to eliminate the last needs for the p Scream when you see a macro that isn't just used for source control (e.g., `#ifdef`) -### ES.31: Don't use macros for constants or "functions" +### ES.31: Don't use macros for constants or "functions" ##### Reason @@ -11404,7 +11404,7 @@ Even if we hadn't left a well-known bug in `SQUARE` there are much better behave Scream when you see a macro that isn't just used for source control (e.g., `#ifdef`) -### ES.32: Use `ALL_CAPS` for all macro names +### ES.32: Use `ALL_CAPS` for all macro names ##### Reason @@ -11420,7 +11420,7 @@ Convention. Readability. Distinguishing macros. Scream when you see a lower case macro. -### ES.33: If you must use macros, give them unique names +### ES.33: If you must use macros, give them unique names ##### Reason @@ -11434,7 +11434,7 @@ Macros do not obey scope rules. ##### Note -Avoid macros if you can: [ES.30](#Res-macros), [ES.31](#Res-macros2), and [ES.32](#Res-ALL_CAPS). +Avoid macros if you can: [ES.30](#res-macros), [ES.31](#res-macros2), and [ES.32](#res-all_caps). However, there are billions of lines of code littered with macros and a long tradition for using and overusing macros. If you are forced to use macros, use long names and supposedly unique prefixes (e.g., your organization's name) to lower the likelihood of a clash. @@ -11442,7 +11442,7 @@ If you are forced to use macros, use long names and supposedly unique prefixes ( Warn against short macro names. -### ES.34: Don't define a (C-style) variadic function +### ES.34: Don't define a (C-style) variadic function ##### Reason @@ -11525,7 +11525,7 @@ This is basically the way `printf` is implemented. Expressions manipulate values. -### ES.40: Avoid complicated expressions +### ES.40: Avoid complicated expressions ##### Reason @@ -11562,7 +11562,7 @@ Some of these expressions are unconditionally bad (e.g., they rely on undefined ##### Note C++17 tightens up the rules for the order of evaluation -(left-to-right except right-to-left in assignments, and the order of evaluation of function arguments is unspecified; [see ES.43](#Res-order)), +(left-to-right except right-to-left in assignments, and the order of evaluation of function arguments is unspecified; [see ES.43](#res-order)), but that doesn't change the fact that complicated expressions are potentially confusing. ##### Note @@ -11594,7 +11594,7 @@ Tricky. How complicated must an expression be to be considered complicated? Writ * implementation defined behavior? * ??? -### ES.41: If in doubt about operator precedence, parenthesize +### ES.41: If in doubt about operator precedence, parenthesize ##### Reason @@ -11625,7 +11625,7 @@ You should know enough not to need parentheses for: * Flag assignment operators not as the leftmost operator. * ??? -### ES.42: Keep use of pointers simple and straightforward +### ES.42: Keep use of pointers simple and straightforward ##### Reason @@ -11634,7 +11634,7 @@ Complicated pointer manipulation is a major source of errors. ##### Note Use `gsl::span` instead. -Pointers should [only refer to single objects](#Ri-array). +Pointers should [only refer to single objects](#ri-array). Pointer arithmetic is fragile and easy to get wrong, the source of many, many bad bugs and security violations. `span` is a bounds-checked, safe type for accessing arrays of data. Access into an array with known bounds using a constant as a subscript can be validated by the compiler. @@ -11821,10 +11821,10 @@ If you want to pass an array, say so: * Flag any indexing expression on an expression or variable of array type (either static array or `std::array`) where the indexer is not a compile-time constant expression with a value between `0` and the upper bound of the array. * Flag any expression that would rely on implicit conversion of an array type to a pointer type. -This rule is part of the [bounds-safety profile](#SS-bounds). +This rule is part of the [bounds-safety profile](#ss-bounds). -### ES.43: Avoid expressions with undefined order of evaluation +### ES.43: Avoid expressions with undefined order of evaluation ##### Reason @@ -11848,7 +11848,7 @@ A good rule of thumb is that you should not read a value twice in an expression Can be detected by a good analyzer. -### ES.44: Don't depend on order of evaluation of function arguments +### ES.44: Don't depend on order of evaluation of function arguments ##### Reason @@ -11881,7 +11881,7 @@ In C++17, these examples work as expected (left to right) and assignments are ev Can be detected by a good analyzer. -### ES.45: Avoid "magic constants"; use symbolic constants +### ES.45: Avoid "magic constants"; use symbolic constants ##### Reason @@ -11910,7 +11910,7 @@ Better still, don't expose constants: Flag literals in code. Give a pass to `0`, `1`, `nullptr`, `\n`, `""`, and others on a positive list. -### ES.46: Avoid lossy (narrowing, truncating) arithmetic conversions +### ES.46: Avoid lossy (narrowing, truncating) arithmetic conversions ##### Reason @@ -11962,7 +11962,7 @@ A good analyzer can detect all narrowing conversions. However, flagging all narr * Flag all `long`->`char`. (I suspect `int`->`char` is very common. Here be dragons! We need data.) * Consider narrowing conversions for function arguments especially suspect. -### ES.47: Use `nullptr` rather than `0` or `NULL` +### ES.47: Use `nullptr` rather than `0` or `NULL` ##### Reason @@ -11984,7 +11984,7 @@ Consider: Flag uses of `0` and `NULL` for pointers. The transformation might be helped by simple program transformation. -### ES.48: Avoid casts +### ES.48: Avoid casts ##### Reason @@ -12028,7 +12028,7 @@ are seriously overused as well as a major source of errors. If you feel the need for a lot of casts, there might be a fundamental design problem. -The [type profile](#Pro-type-reinterpretcast) bans `reinterpret_cast` and C-style casts. +The [type profile](#pro-type-reinterpretcast) bans `reinterpret_cast` and C-style casts. Never cast to `(void)` to ignore a `[[nodiscard]]`return value. If you deliberately want to discard such a result, first think hard about whether that is really a good idea (there is usually a good reason the author of the function or of the return type used `[[nodiscard]]` in the first place). @@ -12046,11 +12046,11 @@ Casts are widely (mis)used. Modern C++ has rules and constructs that eliminate t ##### Enforcement * Flag all C-style casts, including to `void`. -* Flag functional style casts using `Type(value)`. Use `Type{value}` instead which is not narrowing. (See [ES.64](#Res-construct).) -* Flag [identity casts](#Pro-type-identitycast) between pointer types, where the source and target types are the same (#Pro-type-identitycast). -* Flag an explicit pointer cast that could be [implicit](#Pro-type-implicitpointercast). +* Flag functional style casts using `Type(value)`. Use `Type{value}` instead which is not narrowing. (See [ES.64](#res-construct).) +* Flag [identity casts](#pro-type-identitycast) between pointer types, where the source and target types are the same (#pro-type-identitycast). +* Flag an explicit pointer cast that could be [implicit](#pro-type-implicitpointercast). -### ES.49: If you must use a cast, use a named cast +### ES.49: If you must use a cast, use a named cast ##### Reason @@ -12109,11 +12109,11 @@ for example.) ##### Enforcement * Flag all C-style casts, including to `void`. -* Flag functional style casts using `Type(value)`. Use `Type{value}` instead which is not narrowing. (See [ES.64](#Res-construct).) -* The [type profile](#Pro-type-reinterpretcast) bans `reinterpret_cast`. -* The [type profile](#Pro-type-arithmeticcast) warns when using `static_cast` between arithmetic types. +* Flag functional style casts using `Type(value)`. Use `Type{value}` instead which is not narrowing. (See [ES.64](#res-construct).) +* The [type profile](#pro-type-reinterpretcast) bans `reinterpret_cast`. +* The [type profile](#pro-type-arithmeticcast) warns when using `static_cast` between arithmetic types. -### ES.50: Don't cast away `const` +### ES.50: Don't cast away `const` ##### Reason @@ -12290,9 +12290,9 @@ In any variant, we must guard against data races on the `cache` in multi-threade ##### Enforcement * Flag `const_cast`s. -* This rule is part of the [type-safety profile](#Pro-type-constcast) for the related Profile. +* This rule is part of the [type-safety profile](#pro-type-constcast) for the related Profile. -### ES.55: Avoid the need for range checking +### ES.55: Avoid the need for range checking ##### Reason @@ -12309,13 +12309,13 @@ Constructs that cannot overflow do not overflow (and usually run faster): Look for explicit range checks and heuristically suggest alternatives. -### ES.56: Write `std::move()` only when you need to explicitly move an object to another scope +### ES.56: Write `std::move()` only when you need to explicitly move an object to another scope ##### Reason We move, rather than copy, to avoid duplication and for improved performance. -A move typically leaves behind an empty object ([C.64](#Rc-move-semantic)), which can be surprising or even dangerous, so we try to avoid moving from lvalues (they might be accessed later). +A move typically leaves behind an empty object ([C.64](#rc-move-semantic)), which can be surprising or even dangerous, so we try to avoid moving from lvalues (they might be accessed later). ##### Notes @@ -12344,7 +12344,7 @@ Explicit `move` is needed to explicitly move an object to another scope, notably } Usually, a `std::move()` is used as an argument to an `&&` parameter. -And after you do that, assume the object has been moved from (see [C.64](#Rc-move-semantic)) and don't read its state again until you first set it to a new value. +And after you do that, assume the object has been moved from (see [C.64](#rc-move-semantic)) and don't read its state again until you first set it to a new value. void f() { @@ -12431,7 +12431,7 @@ The language already knows that a returned value is a temporary object that can * Flag when `std::forward` is applied to other than a forwarding reference. (More general case of the previous rule to cover the non-moving cases.) * Flag when an object is potentially moved from and the next operation is a `const` operation; there should first be an intervening non-`const` operation, ideally assignment, to first reset the object's value. -### ES.60: Avoid `new` and `delete` outside resource management functions +### ES.60: Avoid `new` and `delete` outside resource management functions ##### Reason @@ -12452,13 +12452,13 @@ This is also known as the rule of "No naked `new`!" There can be code in the `...` part that causes the `delete` never to happen. -**See also**: [R: Resource management](#S-resource) +**See also**: [R: Resource management](#s-resource) ##### Enforcement Flag naked `new`s and naked `delete`s. -### ES.61: Delete arrays using `delete[]` and non-arrays using `delete` +### ES.61: Delete arrays using `delete[]` and non-arrays using `delete` ##### Reason @@ -12475,14 +12475,14 @@ That's what the language requires, and mismatches can lead to resource release e ##### Note -This example not only violates the [no naked `new` rule](#Res-new) as in the previous example, it has many more problems. +This example not only violates the [no naked `new` rule](#res-new) as in the previous example, it has many more problems. ##### Enforcement * Flag mismatched `new` and `delete` if they are in the same scope. * Flag mismatched `new` and `delete` if they are in a constructor/destructor pair. -### ES.62: Don't compare pointers into different arrays +### ES.62: Don't compare pointers into different arrays ##### Reason @@ -12506,7 +12506,7 @@ This example has many more problems. ??? -### ES.63: Don't slice +### ES.63: Don't slice ##### Reason @@ -12533,7 +12533,7 @@ In the rare cases where the slicing was deliberate the code can be surprising. // but this will likely return false The result will be meaningless because the center and radius will not be copied from `c` into `s`. -The first defense against this is to [define the base class `Shape` not to allow this](#Rc-copy-virtual). +The first defense against this is to [define the base class `Shape` not to allow this](#rc-copy-virtual). ##### Alternative @@ -12555,7 +12555,7 @@ For example: Warn against slicing. -### ES.64: Use the `T{e}`notation for construction +### ES.64: Use the `T{e}`notation for construction ##### Reason @@ -12591,7 +12591,7 @@ between platforms with different integer and pointer sizes. ##### Note -[Avoid casts](#Res-casts) (explicit type conversion) and if you must [prefer named casts](#Res-casts-named). +[Avoid casts](#res-casts) (explicit type conversion) and if you must [prefer named casts](#res-casts-named). ##### Note @@ -12603,7 +12603,7 @@ When unambiguous, the `T` can be left out of `T{e}`. ##### Note -The construction notation is the most general [initializer notation](#Res-list). +The construction notation is the most general [initializer notation](#res-list). ##### Exception @@ -12647,7 +12647,7 @@ The main problem left is to find a suitable name for `Count`. Flag the C-style `(T)e` and functional-style `T(e)` casts. -### ES.65: Don't dereference an invalid pointer +### ES.65: Don't dereference an invalid pointer ##### Reason @@ -12666,12 +12666,12 @@ This is a major part of the discussion of [C++'s model for type- and resource-sa **See also**: -* Use [RAII](#Rr-raii) to avoid lifetime problems. -* Use [unique_ptr](#Rf-unique_ptr) to avoid lifetime problems. -* Use [shared_ptr](#Rf-shared_ptr) to avoid lifetime problems. -* Use [references](#Rf-ptr-ref) when `nullptr` isn't a possibility. -* Use [not_null](#Rf-nullptr) to catch unexpected `nullptr` early. -* Use the [bounds profile](#SS-bounds) to avoid range errors. +* Use [RAII](#rr-raii) to avoid lifetime problems. +* Use [unique_ptr](#rf-unique_ptr) to avoid lifetime problems. +* Use [shared_ptr](#rf-shared_ptr) to avoid lifetime problems. +* Use [references](#rf-ptr-ref) when `nullptr` isn't a possibility. +* Use [not_null](#rf-nullptr) to catch unexpected `nullptr` early. +* Use the [bounds profile](#ss-bounds) to avoid range errors. ##### Example @@ -12784,7 +12784,7 @@ Remember that there are other ways of getting an invalid pointer. ##### Enforcement -This rule is part of the [lifetime safety profile](#SS-lifetime) +This rule is part of the [lifetime safety profile](#ss-lifetime) * Flag a dereference of a pointer that points to an object that has gone out of scope * Flag a dereference of a pointer that might have been invalidated by assigning a `nullptr` @@ -12796,7 +12796,7 @@ This rule is part of the [lifetime safety profile](#SS-lifetime) Statements control the flow of control (except for function calls and exception throws, which are expressions). -### ES.70: Prefer a `switch`-statement to an `if`-statement when there is a choice +### ES.70: Prefer a `switch`-statement to an `if`-statement when there is a choice ##### Reason @@ -12835,7 +12835,7 @@ rather than: Flag `if`-`then`-`else` chains that check against constants (only). -### ES.71: Prefer a range-`for`-statement to a `for`-statement when there is a choice +### ES.71: Prefer a range-`for`-statement to a `for`-statement when there is a choice ##### Reason @@ -12885,7 +12885,7 @@ Better still, if the loop variable isn't modified or copied: Look at loops, if a traditional loop just looks at each element of a sequence, and there are no side effects on what it does with the elements, rewrite the loop to a ranged-`for` loop. -### ES.72: Prefer a `for`-statement to a `while`-statement when there is an obvious loop variable +### ES.72: Prefer a `for`-statement to a `while`-statement when there is an obvious loop variable ##### Reason @@ -12909,7 +12909,7 @@ Readability: the complete logic of the loop is visible "up front". The scope of ??? -### ES.73: Prefer a `while`-statement to a `for`-statement when there is no obvious loop variable +### ES.73: Prefer a `while`-statement to a `for`-statement when there is no obvious loop variable ##### Reason @@ -12935,11 +12935,11 @@ Better Flag actions in `for`-initializers and `for`-increments that do not relate to the `for`-condition. -### ES.74: Prefer to declare a loop variable in the initializer part of a `for`-statement +### ES.74: Prefer to declare a loop variable in the initializer part of a `for`-statement -See [ES.6](#Res-cond) +See [ES.6](#res-cond) -### ES.75: Avoid `do`-statements +### ES.75: Avoid `do`-statements ##### Reason @@ -12962,7 +12962,7 @@ Yes, there are genuine examples where a `do`-statement is a clear statement of a Flag `do`-statements. -### ES.76: Avoid `goto` +### ES.76: Avoid `goto` ##### Reason @@ -13005,7 +13005,7 @@ consider `gsl::finally()` as a cleaner and more reliable alternative to `goto ex * Flag `goto`. Better still flag all `goto`s that do not jump from a nested loop to the statement immediately after a nest of loops. -### ES.77: Minimize the use of `break` and `continue` in loops +### ES.77: Minimize the use of `break` and `continue` in loops ##### Reason @@ -13078,14 +13078,14 @@ Often, a loop that uses `continue` can equivalently and as clearly be expressed ##### Note -If you really need to break out a loop, a `break` is typically better than alternatives such as [modifying the loop variable](#Res-loop-counter) or a [`goto`](#Res-goto): +If you really need to break out a loop, a `break` is typically better than alternatives such as [modifying the loop variable](#res-loop-counter) or a [`goto`](#res-goto): ##### Enforcement ??? -### ES.78: Don't rely on implicit fallthrough in `switch` statements +### ES.78: Don't rely on implicit fallthrough in `switch` statements ##### Reason @@ -13150,7 +13150,7 @@ In rare cases if fallthrough is deemed appropriate, be explicit and use the `[[f Flag all implicit fallthroughs from non-empty `case`s. -### ES.79: Use `default` to handle common cases (only) +### ES.79: Use `default` to handle common cases (only) ##### Reason @@ -13223,7 +13223,7 @@ Flag `switch`-statements over an enumeration that don't handle all enumerators a This might yield too many false positives in some code bases; if so, flag only `switch`es that handle most but not all cases (that was the strategy of the very first C++ compiler). -### ES.84: Don't try to declare a local variable with no name +### ES.84: Don't try to declare a local variable with no name ##### Reason @@ -13250,7 +13250,7 @@ Unnamed function arguments are fine. Flag statements that are just a temporary. -### ES.85: Make empty statements visible +### ES.85: Make empty statements visible ##### Reason @@ -13270,7 +13270,7 @@ Readability. Flag empty statements that are not blocks and don't contain comments. -### ES.86: Avoid modifying loop control variables inside the body of raw for-loops +### ES.86: Avoid modifying loop control variables inside the body of raw for-loops ##### Reason @@ -13301,7 +13301,7 @@ The loop control up front should enable correct reasoning about what is happenin Flag variables that are potentially updated (have a non-`const` use) in both the loop control iteration-expression and the loop body. -### ES.87: Don't add redundant `==` or `!=` to conditions +### ES.87: Don't add redundant `==` or `!=` to conditions ##### Reason @@ -13384,9 +13384,9 @@ Easy, just check for redundant use of `!=` and `==` in conditions. -## Arithmetic +## Arithmetic -### ES.100: Don't mix signed and unsigned arithmetic +### ES.100: Don't mix signed and unsigned arithmetic ##### Reason @@ -13406,7 +13406,7 @@ It is harder to spot the problem in more realistic examples. ##### Note Unfortunately, C++ uses signed integers for array subscripts and the standard library uses unsigned integers for container subscripts. -This precludes consistency. Use `gsl::index` for subscripts; [see ES.107](#Res-subscripts). +This precludes consistency. Use `gsl::index` for subscripts; [see ES.107](#res-subscripts). ##### Enforcement @@ -13414,7 +13414,7 @@ This precludes consistency. Use `gsl::index` for subscripts; [see ES.107](#Res-s * (To avoid noise) Do not flag on a mixed signed/unsigned comparison where one of the arguments is `sizeof` or a call to container `.size()` and the other is `ptrdiff_t`. -### ES.101: Use unsigned types for bit manipulation +### ES.101: Use unsigned types for bit manipulation ##### Reason @@ -13437,7 +13437,7 @@ can be surprising for many programmers. * Just about impossible in general because of the use of unsigned subscripts in the standard library * ??? -### ES.102: Use signed types for arithmetic +### ES.102: Use signed types for arithmetic ##### Reason @@ -13493,7 +13493,7 @@ This makes surprises (and bugs) inevitable. // OK, but the number of ints (4294967294) is so large that we should get an exception vector v2(-2); - Use `gsl::index` for subscripts; [see ES.107](#Res-subscripts). + Use `gsl::index` for subscripts; [see ES.107](#res-subscripts). ##### Enforcement @@ -13503,7 +13503,7 @@ This makes surprises (and bugs) inevitable. * (To avoid noise) Do not flag on a mixed signed/unsigned comparison where one of the arguments is `sizeof` or a call to container `.size()` and the other is `ptrdiff_t`. -### ES.103: Don't overflow +### ES.103: Don't overflow ##### Reason @@ -13539,7 +13539,7 @@ Use unsigned types if you really want modular arithmetic. ??? -### ES.104: Don't underflow +### ES.104: Don't underflow ##### Reason @@ -13562,7 +13562,7 @@ Use unsigned types if you really want modular arithmetic. ??? -### ES.105: Don't divide by integer zero +### ES.105: Don't divide by integer zero ##### Reason @@ -13602,7 +13602,7 @@ This also applies to `%`. * Flag division by an integral value that could be zero -### ES.106: Don't try to avoid negative values by using `unsigned` +### ES.106: Don't try to avoid negative values by using `unsigned` ##### Reason @@ -13621,7 +13621,7 @@ Using `unsigned` doesn't actually eliminate the possibility of negative values. These problems with such (perfectly legal) constructs are hard to spot in real code and are the source of many real-world errors. Consider: - unsigned area(unsigned height, unsigned width) { return height*width; } // [see also](#Ri-expects) + unsigned area(unsigned height, unsigned width) { return height*width; } // [see also](#ri-expects) // ... int height; cin >> height; @@ -13667,7 +13667,7 @@ For example See ES.100 Enforcements. -### ES.107: Don't use `unsigned` for subscripts, prefer `gsl::index` +### ES.107: Don't use `unsigned` for subscripts, prefer `gsl::index` ##### Reason @@ -13739,7 +13739,7 @@ Alternatives for users -# Per: Performance +# Per: Performance ??? should this section be in the main guide??? @@ -13750,26 +13750,26 @@ Do not naïvely try to follow them in general code: achieving the goals of low l Performance rule summary: -* [Per.1: Don't optimize without reason](#Rper-reason) -* [Per.2: Don't optimize prematurely](#Rper-Knuth) -* [Per.3: Don't optimize something that's not performance critical](#Rper-critical) -* [Per.4: Don't assume that complicated code is necessarily faster than simple code](#Rper-simple) -* [Per.5: Don't assume that low-level code is necessarily faster than high-level code](#Rper-low) -* [Per.6: Don't make claims about performance without measurements](#Rper-measure) -* [Per.7: Design to enable optimization](#Rper-efficiency) -* [Per.10: Rely on the static type system](#Rper-type) -* [Per.11: Move computation from run time to compile time](#Rper-Comp) -* [Per.12: Eliminate redundant aliases](#Rper-alias) -* [Per.13: Eliminate redundant indirections](#Rper-indirect) -* [Per.14: Minimize the number of allocations and deallocations](#Rper-alloc) -* [Per.15: Do not allocate on a critical branch](#Rper-alloc0) -* [Per.16: Use compact data structures](#Rper-compact) -* [Per.17: Declare the most used member of a time-critical struct first](#Rper-struct) -* [Per.18: Space is time](#Rper-space) -* [Per.19: Access memory predictably](#Rper-access) -* [Per.30: Avoid context switches on the critical path](#Rper-context) - -### Per.1: Don't optimize without reason +* [Per.1: Don't optimize without reason](#rper-reason) +* [Per.2: Don't optimize prematurely](#rper-knuth) +* [Per.3: Don't optimize something that's not performance critical](#rper-critical) +* [Per.4: Don't assume that complicated code is necessarily faster than simple code](#rper-simple) +* [Per.5: Don't assume that low-level code is necessarily faster than high-level code](#rper-low) +* [Per.6: Don't make claims about performance without measurements](#rper-measure) +* [Per.7: Design to enable optimization](#rper-efficiency) +* [Per.10: Rely on the static type system](#rper-type) +* [Per.11: Move computation from run time to compile time](#rper-comp) +* [Per.12: Eliminate redundant aliases](#rper-alias) +* [Per.13: Eliminate redundant indirections](#rper-indirect) +* [Per.14: Minimize the number of allocations and deallocations](#rper-alloc) +* [Per.15: Do not allocate on a critical branch](#rper-alloc0) +* [Per.16: Use compact data structures](#rper-compact) +* [Per.17: Declare the most used member of a time-critical struct first](#rper-struct) +* [Per.18: Space is time](#rper-space) +* [Per.19: Access memory predictably](#rper-access) +* [Per.30: Avoid context switches on the critical path](#rper-context) + +### Per.1: Don't optimize without reason ##### Reason @@ -13781,7 +13781,7 @@ Some people optimize out of habit or because it's fun. ??? -### Per.2: Don't optimize prematurely +### Per.2: Don't optimize prematurely ##### Reason @@ -13789,7 +13789,7 @@ Elaborately optimized code is usually larger and harder to change than unoptimiz ??? -### Per.3: Don't optimize something that's not performance critical +### Per.3: Don't optimize something that's not performance critical ##### Reason @@ -13802,10 +13802,10 @@ If your program spends most of its time waiting for the web or for a human, opti Put another way: If your program spends 4% of its processing time doing computation A and 40% of its time doing computation B, a 50% improvement on A is only as impactful as a 5% improvement on B. (If you don't even know how much -time is spent on A or B, see Per.1 and Per.2.) +time is spent on A or B, see Per.1 and Per.2.) -### Per.4: Don't assume that complicated code is necessarily faster than simple code +### Per.4: Don't assume that complicated code is necessarily faster than simple code ##### Reason @@ -13837,7 +13837,7 @@ Simple code can be very fast. Optimizers sometimes do marvels with simple code ??? -### Per.5: Don't assume that low-level code is necessarily faster than high-level code +### Per.5: Don't assume that low-level code is necessarily faster than high-level code ##### Reason @@ -13849,7 +13849,7 @@ Low-level code sometimes inhibits optimizations. Optimizers sometimes do marvels ??? -### Per.6: Don't make claims about performance without measurements +### Per.6: Don't make claims about performance without measurements ##### Reason @@ -13869,7 +13869,7 @@ Often, you will be surprised. ??? -### Per.7: Design to enable optimization +### Per.7: Design to enable optimization ##### Reason @@ -13927,21 +13927,21 @@ The standard-library specification of `sort` offers those two versions, and more ##### Note -Premature optimization is said to be [the root of all evil](#Rper-Knuth), but that's not a reason to despise performance. +Premature optimization is said to be [the root of all evil](#rper-knuth), but that's not a reason to despise performance. It is never premature to consider what makes a design amenable to improvement, and improved performance is a commonly desired improvement. Aim to build a set of habits that by default results in efficient, maintainable, and optimizable code. In particular, when you write a function that is not a one-off implementation detail, consider * Information passing: -Prefer clean [interfaces](#S-interfaces) carrying sufficient information for later improvement of implementation. +Prefer clean [interfaces](#s-interfaces) carrying sufficient information for later improvement of implementation. Note that information flows into and out of an implementation through the interfaces we provide. -* Compact data: By default, [use compact data](#Rper-compact), such as `std::vector` and [access it in a systematic fashion](#Rper-access). +* Compact data: By default, [use compact data](#rper-compact), such as `std::vector` and [access it in a systematic fashion](#rper-access). If you think you need a linked structure, try to craft the interface so that this structure isn't seen by users. * Function argument passing and return: Distinguish between mutable and non-mutable data. Don't impose a resource management burden on your users. Don't impose spurious run-time indirections on your users. -Use [conventional ways](#Rf-conventional) of passing information through an interface; +Use [conventional ways](#rf-conventional) of passing information through an interface; unconventional and/or "optimized" ways of passing data can seriously complicate later reimplementation. * Abstraction: Don't overgeneralize; a design that tries to cater for every possible use (and misuse) and defers every design decision for later @@ -14001,7 +14001,7 @@ Once your first initial implementation is complete, review it; once you deploy i ##### Note -A need for efficiency does not imply a need for [low-level code](#Rper-low). +A need for efficiency does not imply a need for [low-level code](#rper-low). High-level code isn't necessarily slow or bloated. ##### Note @@ -14026,7 +14026,7 @@ One question that can be useful is ##### Note -This rule does not contradict the [Don't optimize prematurely](#Rper-Knuth) rule. +This rule does not contradict the [Don't optimize prematurely](#rper-knuth) rule. It complements it, encouraging developers to enable later - appropriate and non-premature - optimization, if and where needed. ##### Enforcement @@ -14034,7 +14034,7 @@ It complements it, encouraging developers to enable later - appropriate and non- Tricky. Maybe looking for `void*` function arguments will find examples of interfaces that hinder later optimization. -### Per.10: Rely on the static type system +### Per.10: Rely on the static type system ##### Reason @@ -14042,7 +14042,7 @@ Type violations, weak types (e.g. `void*`s), and low-level code (e.g., manipulat ??? -### Per.11: Move computation from run time to compile time +### Per.11: Move computation from run time to compile time ##### Reason @@ -14121,23 +14121,23 @@ This is admittedly rare, but by factoring out a general computation into separat * Look for functions called with all constant-expression arguments. * Look for macros that could be constexpr. -### Per.12: Eliminate redundant aliases +### Per.12: Eliminate redundant aliases ??? -### Per.13: Eliminate redundant indirections +### Per.13: Eliminate redundant indirections ??? -### Per.14: Minimize the number of allocations and deallocations +### Per.14: Minimize the number of allocations and deallocations ??? -### Per.15: Do not allocate on a critical branch +### Per.15: Do not allocate on a critical branch ??? -### Per.16: Use compact data structures +### Per.16: Use compact data structures ##### Reason @@ -14145,11 +14145,11 @@ Performance is typically dominated by memory access times. ??? -### Per.17: Declare the most used member of a time-critical struct first +### Per.17: Declare the most used member of a time-critical struct first ??? -### Per.18: Space is time +### Per.18: Space is time ##### Reason @@ -14157,7 +14157,7 @@ Performance is typically dominated by memory access times. ??? -### Per.19: Access memory predictably +### Per.19: Access memory predictably ##### Reason @@ -14177,11 +14177,11 @@ Performance is very sensitive to cache performance, and cache algorithms favor s for (int c = 0; c < cols; ++c) sum += matrix[r][c]; -### Per.30: Avoid context switches on the critical path +### Per.30: Avoid context switches on the critical path ??? -# CP: Concurrency and parallelism +# CP: Concurrency and parallelism We often want our computers to do many tasks at the same time (or at least appear to do them at the same time). The reasons for doing so vary (e.g., waiting for many events using only a single processor, processing many data streams simultaneously, or utilizing many hardware facilities) @@ -14221,24 +14221,24 @@ but please think about the majority of programmers who are struggling to get the Concurrency and parallelism rule summary: -* [CP.1: Assume that your code will run as part of a multi-threaded program](#Rconc-multi) -* [CP.2: Avoid data races](#Rconc-races) -* [CP.3: Minimize explicit sharing of writable data](#Rconc-data) -* [CP.4: Think in terms of tasks, rather than threads](#Rconc-task) -* [CP.8: Don't try to use `volatile` for synchronization](#Rconc-volatile) -* [CP.9: Whenever feasible use tools to validate your concurrent code](#Rconc-tools) +* [CP.1: Assume that your code will run as part of a multi-threaded program](#rconc-multi) +* [CP.2: Avoid data races](#rconc-races) +* [CP.3: Minimize explicit sharing of writable data](#rconc-data) +* [CP.4: Think in terms of tasks, rather than threads](#rconc-task) +* [CP.8: Don't try to use `volatile` for synchronization](#rconc-volatile) +* [CP.9: Whenever feasible use tools to validate your concurrent code](#rconc-tools) **See also**: -* [CP.con: Concurrency](#SScp-con) -* [CP.coro: Coroutines](#SScp-coro) -* [CP.par: Parallelism](#SScp-par) -* [CP.mess: Message passing](#SScp-mess) -* [CP.vec: Vectorization](#SScp-vec) -* [CP.free: Lock-free programming](#SScp-free) -* [CP.etc: Etc. concurrency rules](#SScp-etc) +* [CP.con: Concurrency](#sscp-con) +* [CP.coro: Coroutines](#sscp-coro) +* [CP.par: Parallelism](#sscp-par) +* [CP.mess: Message passing](#sscp-mess) +* [CP.vec: Vectorization](#sscp-vec) +* [CP.free: Lock-free programming](#sscp-free) +* [CP.etc: Etc. concurrency rules](#sscp-etc) -### CP.1: Assume that your code will run as part of a multi-threaded program +### CP.1: Assume that your code will run as part of a multi-threaded program ##### Reason @@ -14308,7 +14308,7 @@ was run as part of a multi-threaded program, often years later. Typically, such programs lead to a painful effort to remove data races. Therefore, code that is never intended to run in a multi-threaded environment should be clearly labeled as such and ideally come with compile or run-time enforcement mechanisms to catch those usage bugs early. -### CP.2: Avoid data races +### CP.2: Avoid data races ##### Reason @@ -14317,7 +14317,7 @@ Unless you do, nothing is guaranteed to work and subtle errors will persist. ##### Note In a nutshell, if two threads can access the same object concurrently (without synchronization), and at least one is a writer (performing a non-`const` operation), you have a data race. -For further information of how to use synchronization well to eliminate data races, please consult a good book about concurrency (see [Carefully study the literature](#Rconc-literature)). +For further information of how to use synchronization well to eliminate data races, please consult a good book about concurrency (see [Carefully study the literature](#rconc-literature)). ##### Example, bad @@ -14400,7 +14400,7 @@ There are other ways you can mitigate the chance of data races: * More use of concrete types on the stack (and don't pass pointers around too much) * More use of immutable data (literals, `constexpr`, and `const`) -### CP.3: Minimize explicit sharing of writable data +### CP.3: Minimize explicit sharing of writable data ##### Reason @@ -14434,14 +14434,14 @@ Making `surface_readings` be `const` (with respect to this function) allows reas Immutable data can be safely and efficiently shared. No locking is needed: You can't have a data race on a constant. -See also [CP.mess: Message Passing](#SScp-mess) and [CP.31: prefer pass by value](#Rconc-data-by-value). +See also [CP.mess: Message Passing](#sscp-mess) and [CP.31: prefer pass by value](#rconc-data-by-value). ##### Enforcement ??? -### CP.4: Think in terms of tasks, rather than threads +### CP.4: Think in terms of tasks, rather than threads ##### Reason @@ -14470,7 +14470,7 @@ This is a potent argument for using higher level, more applications-oriented lib ??? -### CP.8: Don't try to use `volatile` for synchronization +### CP.8: Don't try to use `volatile` for synchronization ##### Reason @@ -14520,9 +14520,9 @@ Use a `mutex` for more complicated examples. ##### See also -[(rare) proper uses of `volatile`](#Rconc-volatile2) +[(rare) proper uses of `volatile`](#rconc-volatile2) -### CP.9: Whenever feasible use tools to validate your concurrent code +### CP.9: Whenever feasible use tools to validate your concurrent code Experience shows that concurrent code is exceptionally hard to get right and that compile-time checking, run-time checks, and testing are less effective at finding concurrency errors @@ -14560,39 +14560,39 @@ but it can only identify races seen in a given execution. It is up to an application builder to choose which support tools are valuable for a particular application. -## CP.con: Concurrency +## CP.con: Concurrency This section focuses on relatively ad-hoc uses of multiple threads communicating through shared data. -* For parallel algorithms, see [parallelism](#SScp-par) -* For inter-task communication without explicit sharing, see [messaging](#SScp-mess) -* For vector parallel code, see [vectorization](#SScp-vec) -* For lock-free programming, see [lock free](#SScp-free) +* For parallel algorithms, see [parallelism](#sscp-par) +* For inter-task communication without explicit sharing, see [messaging](#sscp-mess) +* For vector parallel code, see [vectorization](#sscp-vec) +* For lock-free programming, see [lock free](#sscp-free) Concurrency rule summary: -* [CP.20: Use RAII, never plain `lock()`/`unlock()`](#Rconc-raii) -* [CP.21: Use `std::lock()` or `std::scoped_lock` to acquire multiple `mutex`es](#Rconc-lock) -* [CP.22: Never call unknown code while holding a lock (e.g., a callback)](#Rconc-unknown) -* [CP.23: Think of a joining `thread` as a scoped container](#Rconc-join) -* [CP.24: Think of a `thread` as a global container](#Rconc-detach) -* [CP.25: Prefer `gsl::joining_thread` over `std::thread`](#Rconc-joining_thread) -* [CP.26: Don't `detach()` a thread](#Rconc-detached_thread) -* [CP.31: Pass small amounts of data between threads by value, rather than by reference or pointer](#Rconc-data-by-value) -* [CP.32: To share ownership between unrelated `thread`s use `shared_ptr`](#Rconc-shared) -* [CP.40: Minimize context switching](#Rconc-switch) -* [CP.41: Minimize thread creation and destruction](#Rconc-create) -* [CP.42: Don't `wait` without a condition](#Rconc-wait) -* [CP.43: Minimize time spent in a critical section](#Rconc-time) -* [CP.44: Remember to name your `lock_guard`s and `unique_lock`s](#Rconc-name) -* [CP.50: Define a `mutex` together with the data it guards. Use `synchronized_value` where possible](#Rconc-mutex) +* [CP.20: Use RAII, never plain `lock()`/`unlock()`](#rconc-raii) +* [CP.21: Use `std::lock()` or `std::scoped_lock` to acquire multiple `mutex`es](#rconc-lock) +* [CP.22: Never call unknown code while holding a lock (e.g., a callback)](#rconc-unknown) +* [CP.23: Think of a joining `thread` as a scoped container](#rconc-join) +* [CP.24: Think of a `thread` as a global container](#rconc-detach) +* [CP.25: Prefer `gsl::joining_thread` over `std::thread`](#rconc-joining_thread) +* [CP.26: Don't `detach()` a thread](#rconc-detached_thread) +* [CP.31: Pass small amounts of data between threads by value, rather than by reference or pointer](#rconc-data-by-value) +* [CP.32: To share ownership between unrelated `thread`s use `shared_ptr`](#rconc-shared) +* [CP.40: Minimize context switching](#rconc-switch) +* [CP.41: Minimize thread creation and destruction](#rconc-create) +* [CP.42: Don't `wait` without a condition](#rconc-wait) +* [CP.43: Minimize time spent in a critical section](#rconc-time) +* [CP.44: Remember to name your `lock_guard`s and `unique_lock`s](#rconc-name) +* [CP.50: Define a `mutex` together with the data it guards. Use `synchronized_value` where possible](#rconc-mutex) * ??? when to use a spinlock * ??? when to use `try_lock()` * ??? when to prefer `lock_guard` over `unique_lock` * ??? Time multiplexing * ??? when/how to use `new thread` -### CP.20: Use RAII, never plain `lock()`/`unlock()` +### CP.20: Use RAII, never plain `lock()`/`unlock()` ##### Reason @@ -14624,7 +14624,7 @@ Sooner or later, someone will forget the `mtx.unlock()`, place a `return` in the Flag calls of member `lock()` and `unlock()`. ??? -### CP.21: Use `std::lock()` or `std::scoped_lock` to acquire multiple `mutex`es +### CP.21: Use `std::lock()` or `std::scoped_lock` to acquire multiple `mutex`es ##### Reason @@ -14683,7 +14683,7 @@ Detect the acquisition of multiple `mutex`es. This is undecidable in general, but catching common simple examples (like the one above) is easy. -### CP.22: Never call unknown code while holding a lock (e.g., a callback) +### CP.22: Never call unknown code while holding a lock (e.g., a callback) ##### Reason @@ -14727,7 +14727,7 @@ If, as it is likely, `f()` invokes operations on `*this`, we must make sure that * Flag calling a callback with a non-recursive `mutex` held -### CP.23: Think of a joining `thread` as a scoped container +### CP.23: Think of a joining `thread` as a scoped container ##### Reason @@ -14765,7 +14765,7 @@ these `thread`s can be seen as just a function object called from `some_fct`. Ensure that `joining_thread`s don't `detach()`. After that, the usual lifetime and ownership (for local objects) enforcement applies. -### CP.24: Think of a `thread` as a global container +### CP.24: Think of a `thread` as a global container ##### Reason @@ -14812,7 +14812,7 @@ of objects with static storage duration, and thus accesses to such objects might ##### Note -This rule is redundant if you [don't `detach()`](#Rconc-detached_thread) and [use `gsl::joining_thread`](#Rconc-joining_thread). +This rule is redundant if you [don't `detach()`](#rconc-detached_thread) and [use `gsl::joining_thread`](#rconc-joining_thread). However, converting code to follow those guidelines could be difficult and even impossible for third-party libraries. In such cases, the rule becomes essential for lifetime safety and type safety. @@ -14825,7 +14825,7 @@ after that, the usual lifetime and ownership (for global objects) enforcement ap Flag attempts to pass local variables to a thread that might `detach()`. -### CP.25: Prefer `gsl::joining_thread` over `std::thread` +### CP.25: Prefer `gsl::joining_thread` over `std::thread` ##### Reason @@ -14867,7 +14867,7 @@ It is harder to ensure absence of errors in detached threads (and potentially de ##### Note Make "immortal threads" globals, put them in an enclosing scope, or put them on the free store rather than `detach()`. -[Don't `detach`](#Rconc-detached_thread). +[Don't `detach`](#rconc-detached_thread). ##### Note @@ -14878,10 +14878,10 @@ Because of old code and third party libraries using `std::thread`, this rule can Flag uses of `std::thread`: * Suggest use of `gsl::joining_thread` or C++20 `std::jthread`. -* Suggest ["exporting ownership"](#Rconc-detached_thread) to an enclosing scope if it detaches. +* Suggest ["exporting ownership"](#rconc-detached_thread) to an enclosing scope if it detaches. * Warn if it is not obvious whether a thread joins or detaches. -### CP.26: Don't `detach()` a thread +### CP.26: Don't `detach()` a thread ##### Reason @@ -14934,7 +14934,7 @@ Sometimes, we need to separate the point of creation from the point of ownership Flag `detach()`. -### CP.31: Pass small amounts of data between threads by value, rather than by reference or pointer +### CP.31: Pass small amounts of data between threads by value, rather than by reference or pointer ##### Reason @@ -14971,7 +14971,7 @@ message passing or shared memory. ??? -### CP.32: To share ownership between unrelated `thread`s use `shared_ptr` +### CP.32: To share ownership between unrelated `thread`s use `shared_ptr` ##### Reason @@ -14994,7 +14994,7 @@ safe way to ensure proper deletion. ??? -### CP.40: Minimize context switching +### CP.40: Minimize context switching ##### Reason @@ -15009,7 +15009,7 @@ Context switches are expensive. ??? -### CP.41: Minimize thread creation and destruction +### CP.41: Minimize thread creation and destruction ##### Reason @@ -15065,7 +15065,7 @@ If your system has a good message queue, use it. ??? -### CP.42: Don't `wait` without a condition +### CP.42: Don't `wait` without a condition ##### Reason @@ -15135,7 +15135,7 @@ it will immediately go back to sleep, waiting. Flag all `wait`s without conditions. -### CP.43: Minimize time spent in a critical section +### CP.43: Minimize time spent in a critical section ##### Reason @@ -15165,7 +15165,7 @@ We could rewrite this to do2(); // cleanup: does not need locking } -But that compromises safety and violates the [use RAII](#Rconc-raii) rule. +But that compromises safety and violates the [use RAII](#rconc-raii) rule. Instead, add a block for the critical section: void do_something() // OK @@ -15184,7 +15184,7 @@ Impossible in general. Flag "naked" `lock()` and `unlock()`. -### CP.44: Remember to name your `lock_guard`s and `unique_lock`s +### CP.44: Remember to name your `lock_guard`s and `unique_lock`s ##### Reason @@ -15215,7 +15215,7 @@ Flag all unnamed `lock_guard`s and `unique_lock`s. -### CP.50: Define a `mutex` together with the data it guards. Use `synchronized_value` where possible +### CP.50: Define a `mutex` together with the data it guards. Use `synchronized_value` where possible ##### Reason @@ -15243,17 +15243,17 @@ See the [WG21 proposal](http://wg21.link/p0290) to add `synchronized_value` to a ??? Possible? -## CP.coro: Coroutines +## CP.coro: Coroutines This section focuses on uses of coroutines. Coroutine rule summary: -* [CP.51: Do not use capturing lambdas that are coroutines](#Rcoro-capture) -* [CP.52: Do not hold locks or other synchronization primitives across suspension points](#Rcoro-locks) -* [CP.53: Parameters to coroutines should not be passed by reference](#Rcoro-reference-parameters) +* [CP.51: Do not use capturing lambdas that are coroutines](#rcoro-capture) +* [CP.52: Do not hold locks or other synchronization primitives across suspension points](#rcoro-locks) +* [CP.53: Parameters to coroutines should not be passed by reference](#rcoro-reference-parameters) -### CP.51: Do not use capturing lambdas that are coroutines +### CP.51: Do not use capturing lambdas that are coroutines ##### Reason @@ -15311,7 +15311,7 @@ Use a function for coroutines. Flag a lambda that is a coroutine and has a non-empty capture list. -### CP.52: Do not hold locks or other synchronization primitives across suspension points +### CP.52: Do not hold locks or other synchronization primitives across suspension points ##### Reason @@ -15353,7 +15353,7 @@ This pattern is also bad for performance. When a suspension point is reached, su Flag all lock guards that are not destructed before a coroutine suspends. -### CP.53: Parameters to coroutines should not be passed by reference +### CP.53: Parameters to coroutines should not be passed by reference ##### Reason @@ -15383,13 +15383,13 @@ This problem does not apply to reference parameters that are only accessed befor ##### Note -The same danger applies to output parameters. [F.20: For "out" output values, prefer return values to output parameters](#Rf-out) discourages output parameters. Coroutines should avoid them entirely. +The same danger applies to output parameters. [F.20: For "out" output values, prefer return values to output parameters](#rf-out) discourages output parameters. Coroutines should avoid them entirely. ##### Enforcement Flag all reference parameters to a coroutine. -## CP.par: Parallelism +## CP.par: Parallelism By "parallelism" we refer to performing a task (more or less) simultaneously ("in parallel with") on many data items. @@ -15402,7 +15402,7 @@ Parallelism rule summary: -## CP.mess: Message passing +## CP.mess: Message passing The standard-library facilities are quite low-level, focused on the needs of close-to-the-hardware critical programming using `thread`s, `mutex`es, `atomic` types, etc. Most people shouldn't work at this level: it's error-prone and development is slow. @@ -15411,8 +15411,8 @@ This section looks at passing messages so that a programmer doesn't have to do e Message passing rules summary: -* [CP.60: Use a `future` to return a value from a concurrent task](#Rconc-future) -* [CP.61: Use `async()` to spawn concurrent tasks](#Rconc-async) +* [CP.60: Use a `future` to return a value from a concurrent task](#rconc-future) +* [CP.61: Use `async()` to spawn concurrent tasks](#rconc-async) * message queues * messaging libraries @@ -15421,7 +15421,7 @@ Message passing rules summary: ??? Is `std::async` worth using in light of future (and even existing, as libraries) parallelism facilities? What should the guidelines recommend if someone wants to parallelize, e.g., `std::accumulate` (with the additional precondition of commutativity), or merge sort? -### CP.60: Use a `future` to return a value from a concurrent task +### CP.60: Use a `future` to return a value from a concurrent task ##### Reason @@ -15440,11 +15440,11 @@ There is no explicit locking and both correct (value) return and error (exceptio ??? -### CP.61: Use `async()` to spawn concurrent tasks +### CP.61: Use `async()` to spawn concurrent tasks ##### Reason -Similar to [R.12](#Rr-immediate-alloc), which tells you to avoid raw owning pointers, you should +Similar to [R.12](#rr-immediate-alloc), which tells you to avoid raw owning pointers, you should also avoid raw threads and raw promises where possible. Use a factory function such as `std::async`, which handles spawning or reusing a thread without exposing raw threads to your own code. @@ -15524,7 +15524,7 @@ objects, never with raw `thread`, `promise`, or `packaged_task` objects. ??? -## CP.vec: Vectorization +## CP.vec: Vectorization Vectorization is a technique for executing a number of tasks concurrently without introducing explicit synchronization. An operation is simply applied to elements of a data structure (a vector, an array, etc.) in parallel. @@ -15536,7 +15536,7 @@ Vectorization rule summary: * ??? * ??? -## CP.free: Lock-free programming +## CP.free: Lock-free programming Synchronization using `mutex`es and `condition_variable`s can be relatively expensive. Furthermore, it can lead to deadlock. @@ -15546,18 +15546,18 @@ Lock-free programming is also used to implement higher-level concurrency mechani Lock-free programming rule summary: -* [CP.100: Don't use lock-free programming unless you absolutely have to](#Rconc-lockfree) -* [CP.101: Distrust your hardware/compiler combination](#Rconc-distrust) -* [CP.102: Carefully study the literature](#Rconc-literature) +* [CP.100: Don't use lock-free programming unless you absolutely have to](#rconc-lockfree) +* [CP.101: Distrust your hardware/compiler combination](#rconc-distrust) +* [CP.102: Carefully study the literature](#rconc-literature) * how/when to use atomics * avoid starvation * use a lock-free data structure rather than hand-crafting specific lock-free access -* [CP.110: Do not write your own double-checked locking for initialization](#Rconc-double) -* [CP.111: Use a conventional pattern if you really need double-checked locking](#Rconc-double-pattern) +* [CP.110: Do not write your own double-checked locking for initialization](#rconc-double) +* [CP.111: Use a conventional pattern if you really need double-checked locking](#rconc-double-pattern) * how/when to compare and swap -### CP.100: Don't use lock-free programming unless you absolutely have to +### CP.100: Don't use lock-free programming unless you absolutely have to ##### Reason @@ -15590,7 +15590,7 @@ Higher-level concurrency mechanisms, such as `thread`s and `mutex`es are impleme **Alternative**: Use lock-free data structures implemented by others as part of some library. -### CP.101: Distrust your hardware/compiler combination +### CP.101: Distrust your hardware/compiler combination ##### Reason @@ -15610,7 +15610,7 @@ Testing - often to an extreme extent - is essential. Have strong rules for re-testing in place that covers any change in hardware, operating system, compiler, and libraries. -### CP.102: Carefully study the literature +### CP.102: Carefully study the literature ##### Reason @@ -15630,7 +15630,7 @@ Become an expert before shipping lock-free code for others to use. * Damian Dechev, Peter Pirkelbauer, Nicolas Rouquette, and Bjarne Stroustrup: Semantically Enhanced Containers for Concurrent Real-Time Systems. Proc. 16th Annual IEEE International Conference and Workshop on the Engineering of Computer Based Systems (IEEE ECBS). April 2009. * Maurice Herlihy, Nir Shavit, Victor Luchangco, Michael Spear, "The Art of Multiprocessor Programming", 2nd ed. September 2020 -### CP.110: Do not write your own double-checked locking for initialization +### CP.110: Do not write your own double-checked locking for initialization ##### Reason @@ -15673,17 +15673,17 @@ Example with thread-safe static local variables of C++11. ??? Is it possible to detect the idiom? -### CP.111: Use a conventional pattern if you really need double-checked locking +### CP.111: Use a conventional pattern if you really need double-checked locking ##### Reason -Double-checked locking is easy to mess up. If you really need to write your own double-checked locking, in spite of the rules [CP.110: Do not write your own double-checked locking for initialization](#Rconc-double) and [CP.100: Don't use lock-free programming unless you absolutely have to](#Rconc-lockfree), then do it in a conventional pattern. +Double-checked locking is easy to mess up. If you really need to write your own double-checked locking, in spite of the rules [CP.110: Do not write your own double-checked locking for initialization](#rconc-double) and [CP.100: Don't use lock-free programming unless you absolutely have to](#rconc-lockfree), then do it in a conventional pattern. -The uses of the double-checked locking pattern that are not in violation of [CP.110: Do not write your own double-checked locking for initialization](#Rconc-double) arise when a non-thread-safe action is both hard and rare, and there exists a fast thread-safe test that can be used to guarantee that the action is not needed, but cannot be used to guarantee the converse. +The uses of the double-checked locking pattern that are not in violation of [CP.110: Do not write your own double-checked locking for initialization](#rconc-double) arise when a non-thread-safe action is both hard and rare, and there exists a fast thread-safe test that can be used to guarantee that the action is not needed, but cannot be used to guarantee the converse. ##### Example, bad -The use of volatile does not make the first check thread-safe, see also [CP.200: Use `volatile` only to talk to non-C++ memory](#Rconc-volatile2) +The use of volatile does not make the first check thread-safe, see also [CP.200: Use `volatile` only to talk to non-C++ memory](#rconc-volatile2) mutex action_mutex; volatile bool action_needed; @@ -15727,14 +15727,14 @@ Fine-tuned memory order might be beneficial where acquire load is more efficient ??? Is it possible to detect the idiom? -## CP.etc: Etc. concurrency rules +## CP.etc: Etc. concurrency rules These rules defy simple categorization: -* [CP.200: Use `volatile` only to talk to non-C++ memory](#Rconc-volatile2) -* [CP.201: ??? Signals](#Rconc-signal) +* [CP.200: Use `volatile` only to talk to non-C++ memory](#rconc-volatile2) +* [CP.201: ??? Signals](#rconc-signal) -### CP.200: Use `volatile` only to talk to non-C++ memory +### CP.200: Use `volatile` only to talk to non-C++ memory ##### Reason @@ -15789,19 +15789,19 @@ The same applies almost as strongly to data members, for the same reason. ##### Note -In C++, unlike in some other languages, `volatile` has [nothing to do with synchronization](#Rconc-volatile). +In C++, unlike in some other languages, `volatile` has [nothing to do with synchronization](#rconc-volatile). ##### Enforcement * Flag `volatile T` local and data members; almost certainly you intended to use `atomic` instead. * ??? -### CP.201: ??? Signals +### CP.201: ??? Signals ???UNIX signal handling???. Might be worth reminding how little is async-signal-safe, and how to communicate with a signal handler (best is probably "not at all") -# E: Error handling +# E: Error handling Error handling involves: @@ -15823,39 +15823,39 @@ The rules are designed to help avoid several kinds of errors: Error-handling rule summary: -* [E.1: Develop an error-handling strategy early in a design](#Re-design) -* [E.2: Throw an exception to signal that a function can't perform its assigned task](#Re-throw) -* [E.3: Use exceptions for error handling only](#Re-errors) -* [E.4: Design your error-handling strategy around invariants](#Re-design-invariants) -* [E.5: Let a constructor establish an invariant, and throw if it cannot](#Re-invariant) -* [E.6: Use RAII to prevent leaks](#Re-raii) -* [E.7: State your preconditions](#Re-precondition) -* [E.8: State your postconditions](#Re-postcondition) +* [E.1: Develop an error-handling strategy early in a design](#re-design) +* [E.2: Throw an exception to signal that a function can't perform its assigned task](#re-throw) +* [E.3: Use exceptions for error handling only](#re-errors) +* [E.4: Design your error-handling strategy around invariants](#re-design-invariants) +* [E.5: Let a constructor establish an invariant, and throw if it cannot](#re-invariant) +* [E.6: Use RAII to prevent leaks](#re-raii) +* [E.7: State your preconditions](#re-precondition) +* [E.8: State your postconditions](#re-postcondition) -* [E.12: Use `noexcept` when exiting a function because of a `throw` is impossible or unacceptable](#Re-noexcept) -* [E.13: Never throw while being the direct owner of an object](#Re-never-throw) -* [E.14: Use purpose-designed user-defined types as exceptions (not built-in types)](#Re-exception-types) -* [E.15: Throw by value, catch exceptions from a hierarchy by reference](#Re-exception-ref) -* [E.16: Destructors, deallocation, `swap`, and exception type copy/move construction must never fail](#Re-never-fail) -* [E.17: Don't try to catch every exception in every function](#Re-not-always) -* [E.18: Minimize the use of explicit `try`/`catch`](#Re-catch) -* [E.19: Use a `final_action` object to express cleanup if no suitable resource handle is available](#Re-finally) +* [E.12: Use `noexcept` when exiting a function because of a `throw` is impossible or unacceptable](#re-noexcept) +* [E.13: Never throw while being the direct owner of an object](#re-never-throw) +* [E.14: Use purpose-designed user-defined types as exceptions (not built-in types)](#re-exception-types) +* [E.15: Throw by value, catch exceptions from a hierarchy by reference](#re-exception-ref) +* [E.16: Destructors, deallocation, `swap`, and exception type copy/move construction must never fail](#re-never-fail) +* [E.17: Don't try to catch every exception in every function](#re-not-always) +* [E.18: Minimize the use of explicit `try`/`catch`](#re-catch) +* [E.19: Use a `final_action` object to express cleanup if no suitable resource handle is available](#re-finally) -* [E.25: If you can't throw exceptions, simulate RAII for resource management](#Re-no-throw-raii) -* [E.26: If you can't throw exceptions, consider failing fast](#Re-no-throw-crash) -* [E.27: If you can't throw exceptions, use error codes systematically](#Re-no-throw-codes) -* [E.28: Avoid error handling based on global state (e.g. `errno`)](#Re-no-throw) +* [E.25: If you can't throw exceptions, simulate RAII for resource management](#re-no-throw-raii) +* [E.26: If you can't throw exceptions, consider failing fast](#re-no-throw-crash) +* [E.27: If you can't throw exceptions, use error codes systematically](#re-no-throw-codes) +* [E.28: Avoid error handling based on global state (e.g. `errno`)](#re-no-throw) -* [E.30: Don't use exception specifications](#Re-specifications) -* [E.31: Properly order your `catch`-clauses](#Re_catch) +* [E.30: Don't use exception specifications](#re-specifications) +* [E.31: Properly order your `catch`-clauses](#re_catch) -### E.1: Develop an error-handling strategy early in a design +### E.1: Develop an error-handling strategy early in a design ##### Reason A consistent and complete strategy for handling errors and resource leaks is hard to retrofit into a system. -### E.2: Throw an exception to signal that a function can't perform its assigned task +### E.2: Throw an exception to signal that a function can't perform its assigned task ##### Reason @@ -15897,7 +15897,7 @@ However, that's a bit circular because "what is exceptional?" Examples: * A precondition that cannot be met -* A constructor that cannot construct an object (failure to establish its class's [invariant](#Rc-struct)) +* A constructor that cannot construct an object (failure to establish its class's [invariant](#rc-struct)) * An out-of-range error (e.g., `v[v.size()] = 7`) * Inability to acquire a resource (e.g., the network is down) @@ -15912,17 +15912,17 @@ Don't use a `throw` as simply an alternative way of returning a value from a fun Some systems, such as hard-real-time systems require a guarantee that an action is taken in a (typically short) constant maximum time known before execution starts. Such systems can use exceptions only if there is tool support for accurately predicting the maximum time to recover from a `throw`. -**See also**: [RAII](#Re-raii) +**See also**: [RAII](#re-raii) -**See also**: [discussion](#Sd-noexcept) +**See also**: [discussion](#sd-noexcept) ##### Note -Before deciding that you cannot afford or don't like exception-based error handling, have a look at the [alternatives](#Re-no-throw-raii); +Before deciding that you cannot afford or don't like exception-based error handling, have a look at the [alternatives](#re-no-throw-raii); they have their own complexities and problems. Also, as far as possible, measure before making claims about efficiency. -### E.3: Use exceptions for error handling only +### E.3: Use exceptions for error handling only ##### Reason @@ -15952,7 +15952,7 @@ There is nothing exceptional about finding a value in a `vector`. Would need to be heuristic. Look for exception values "leaked" out of `catch` clauses. -### E.4: Design your error-handling strategy around invariants +### E.4: Design your error-handling strategy around invariants ##### Reason @@ -15960,13 +15960,13 @@ To use an object it must be in a valid state (defined formally or informally by ##### Note -An [invariant](#Rc-struct) is a logical condition for the members of an object that a constructor must establish for the public member functions to assume. +An [invariant](#rc-struct) is a logical condition for the members of an object that a constructor must establish for the public member functions to assume. ##### Enforcement ??? -### E.5: Let a constructor establish an invariant, and throw if it cannot +### E.5: Let a constructor establish an invariant, and throw if it cannot ##### Reason @@ -15992,13 +15992,13 @@ The class invariant - here stated as a comment - is established by the construct `new` throws if it cannot allocate the required memory. The operators, notably the subscript operator, rely on the invariant. -**See also**: [If a constructor cannot construct a valid object, throw an exception](#Rc-throw) +**See also**: [If a constructor cannot construct a valid object, throw an exception](#rc-throw) ##### Enforcement Flag classes with `private` state without a constructor (public, protected, or private). -### E.6: Use RAII to prevent leaks +### E.6: Use RAII to prevent leaks ##### Reason @@ -16064,7 +16064,7 @@ That's even simpler and safer, and often more efficient. ##### Note If there is no obvious resource handle and for some reason defining a proper RAII object/handle is infeasible, -as a last resort, cleanup actions can be represented by a [`final_action`](#Re-finally) object. +as a last resort, cleanup actions can be represented by a [`final_action`](#re-finally) object. ##### Note @@ -16104,29 +16104,29 @@ One strategy is to add a `valid()` operation to every resource handle: Obviously, this increases the size of the code, doesn't allow for implicit propagation of "exceptions" (`valid()` checks), and `valid()` checks can be forgotten. Prefer to use exceptions. -**See also**: [Use of `noexcept`](#Re-noexcept) +**See also**: [Use of `noexcept`](#re-noexcept) ##### Enforcement ??? -### E.7: State your preconditions +### E.7: State your preconditions ##### Reason To avoid interface errors. -**See also**: [precondition rule](#Ri-pre) +**See also**: [precondition rule](#ri-pre) -### E.8: State your postconditions +### E.8: State your postconditions ##### Reason To avoid interface errors. -**See also**: [postcondition rule](#Ri-post) +**See also**: [postcondition rule](#ri-post) -### E.12: Use `noexcept` when exiting a function because of a `throw` is impossible or unacceptable +### E.12: Use `noexcept` when exiting a function because of a `throw` is impossible or unacceptable ##### Reason @@ -16159,13 +16159,13 @@ That is, I consider memory exhaustion a serious design error (on par with hardwa ##### Note -Do not use traditional [exception-specifications](#Re-specifications). +Do not use traditional [exception-specifications](#re-specifications). ##### See also -[discussion](#Sd-noexcept). +[discussion](#sd-noexcept). -### E.13: Never throw while being the direct owner of an object +### E.13: Never throw while being the direct owner of an object ##### Reason @@ -16203,9 +16203,9 @@ Another solution (often better) would be to use a local variable to eliminate ex If you have a local "thing" that requires cleanup, but is not represented by an object with a destructor, such cleanup must also be done before a `throw`. -Sometimes, [`finally()`](#Re-finally) can make such unsystematic cleanup a bit more manageable. +Sometimes, [`finally()`](#re-finally) can make such unsystematic cleanup a bit more manageable. -### E.14: Use purpose-designed user-defined types as exceptions (not built-in types) +### E.14: Use purpose-designed user-defined types as exceptions (not built-in types) ##### Reason @@ -16260,7 +16260,7 @@ no useful information can be added at the point of detection: Catch `throw` of built-in types and `std::exception`. -### E.15: Throw by value, catch exceptions from a hierarchy by reference +### E.15: Throw by value, catch exceptions from a hierarchy by reference ##### Reason @@ -16288,7 +16288,7 @@ or - typically better still - a `const` reference: catch (const base_class& e) { /* ... */ } -Most handlers do not modify their exception and in general we [recommend use of `const`](#Res-const). +Most handlers do not modify their exception and in general we [recommend use of `const`](#res-const). ##### Note @@ -16296,14 +16296,14 @@ Catch by value can be appropriate for a small value type such as an `enum` value ##### Note -To rethrow a caught exception use `throw;` not `throw e;`. Using `throw e;` would throw a new copy of `e` (sliced to the static type `std::exception`, when the exception is caught by `catch (const std::exception& e)`) instead of rethrowing the original exception of type `std::runtime_error`. (But keep [Don't try to catch every exception in every function](#Re-not-always) and [Minimize the use of explicit `try`/`catch`](#Re-catch) in mind.) +To rethrow a caught exception use `throw;` not `throw e;`. Using `throw e;` would throw a new copy of `e` (sliced to the static type `std::exception`, when the exception is caught by `catch (const std::exception& e)`) instead of rethrowing the original exception of type `std::runtime_error`. (But keep [Don't try to catch every exception in every function](#re-not-always) and [Minimize the use of explicit `try`/`catch`](#re-catch) in mind.) ##### Enforcement * Flag catching by value of a type that has a virtual function. * Flag throwing raw pointers. -### E.16: Destructors, deallocation, `swap`, and exception type copy/move construction must never fail +### E.16: Destructors, deallocation, `swap`, and exception type copy/move construction must never fail ##### Reason @@ -16339,7 +16339,7 @@ The standard library assumes that destructors, deallocation functions (e.g., `op * Deallocation functions, including `operator delete`, must be `noexcept`. * `swap` functions must be `noexcept`. * Most destructors are implicitly `noexcept` by default. -* Also, [make move operations `noexcept`](#Rc-move-noexcept). +* Also, [make move operations `noexcept`](#rc-move-noexcept). * If writing a type intended to be used as an exception type, ensure its copy constructor is `noexcept`. In general we cannot mechanically enforce this, because we do not know whether a type is intended to be used as an exception type. * Try not to `throw` a type whose copy constructor is not `noexcept`. In general we cannot mechanically enforce this, because even `throw std::string(...)` could throw but does not in practice. @@ -16348,15 +16348,15 @@ The standard library assumes that destructors, deallocation functions (e.g., `op * Catch destructors, deallocation operations, and `swap`s that `throw`. * Catch such operations that are not `noexcept`. -**See also**: [discussion](#Sd-never-fail) +**See also**: [discussion](#sd-never-fail) -### E.17: Don't try to catch every exception in every function +### E.17: Don't try to catch every exception in every function ##### Reason Catching an exception in a function that cannot take a meaningful recovery action leads to complexity and waste. Let an exception propagate until it reaches a function that can handle it. -Let cleanup actions on the unwinding path be handled by [RAII](#Re-raii). +Let cleanup actions on the unwinding path be handled by [RAII](#re-raii). ##### Example, don't @@ -16376,7 +16376,7 @@ Let cleanup actions on the unwinding path be handled by [RAII](#Re-raii). * Flag nested try-blocks. * Flag source code files with a too high ratio of try-blocks to functions. (??? Problem: define "too high") -### E.18: Minimize the use of explicit `try`/`catch` +### E.18: Minimize the use of explicit `try`/`catch` ##### Reason @@ -16412,14 +16412,14 @@ Better: ##### Alternatives -* proper resource handles and [RAII](#Re-raii) -* [`finally`](#Re-finally) +* proper resource handles and [RAII](#re-raii) +* [`finally`](#re-finally) ##### Enforcement ??? hard, needs a heuristic -### E.19: Use a `final_action` object to express cleanup if no suitable resource handle is available +### E.19: Use a `final_action` object to express cleanup if no suitable resource handle is available ##### Reason @@ -16437,23 +16437,23 @@ Better: ##### Note `finally` is not as messy as `try`/`catch`, but it is still ad-hoc. -Prefer [proper resource management objects](#Re-raii). +Prefer [proper resource management objects](#re-raii). Consider `finally` a last resort. ##### Note -Use of `finally` is a systematic and reasonably clean alternative to the old [`goto exit;` technique](#Re-no-throw-codes) +Use of `finally` is a systematic and reasonably clean alternative to the old [`goto exit;` technique](#re-no-throw-codes) for dealing with cleanup where resource management is not systematic. ##### Enforcement Heuristic: Detect `goto exit;` -### E.25: If you can't throw exceptions, simulate RAII for resource management +### E.25: If you can't throw exceptions, simulate RAII for resource management ##### Reason -Even without exceptions, [RAII](#Re-raii) is usually the best and most systematic way of dealing with resources. +Even without exceptions, [RAII](#re-raii) is usually the best and most systematic way of dealing with resources. ##### Note @@ -16471,13 +16471,13 @@ Some hard-real-time systems are an example: An operation has to be completed wit In the absence of appropriate time estimation tools, this is hard to guarantee for exceptions. Such systems (e.g. flight control software) typically also ban the use of dynamic (heap) memory. -So, the primary guideline for error handling is "use exceptions and [RAII](#Re-raii)." +So, the primary guideline for error handling is "use exceptions and [RAII](#re-raii)." This section deals with the cases where you either do not have an efficient implementation of exceptions, or have such a rat's nest of old-style code (e.g., lots of pointers, ill-defined ownership, and lots of unsystematic error handling based on tests of error codes) that it is infeasible to introduce simple and systematic exception handling. -Before condemning exceptions or complaining too much about their cost, consider examples of the use of [error codes](#Re-no-throw-codes). +Before condemning exceptions or complaining too much about their cost, consider examples of the use of [error codes](#re-no-throw-codes). Consider the cost and complexity of the use of error codes. If performance is your worry, measure. @@ -16504,19 +16504,19 @@ If we cannot throw an exception, we can simulate this RAII style of resource han The problem is of course that the caller now has to remember to test the return value. To encourage doing so, consider adding a `[[nodiscard]]`. -**See also**: [Discussion](#Sd-???) +**See also**: [Discussion](#sd-???) ##### Enforcement Possible (only) for specific versions of this idea: e.g., test for systematic test of `valid()` after resource handle construction -### E.26: If you can't throw exceptions, consider failing fast +### E.26: If you can't throw exceptions, consider failing fast ##### Reason If you can't do a good job at recovering, at least you can get out before too much consequential damage is done. -**See also**: [Simulating RAII](#Re-no-throw-raii) +**See also**: [Simulating RAII](#re-no-throw-raii) ##### Note @@ -16553,13 +16553,13 @@ Typically, it is a good idea to log the reason for the "crash" before exiting. Awkward -### E.27: If you can't throw exceptions, use error codes systematically +### E.27: If you can't throw exceptions, use error codes systematically ##### Reason Systematic use of any error-handling strategy minimizes the chance of forgetting to handle an error. -**See also**: [Simulating RAII](#Re-no-throw-raii) +**See also**: [Simulating RAII](#re-no-throw-raii) ##### Note @@ -16589,7 +16589,7 @@ or a pair of values can be returned. // ... } -This approach fits with [simulated RAII resource management](#Re-no-throw-raii). +This approach fits with [simulated RAII resource management](#re-no-throw-raii). The `valid()` function could return an `error_indicator` (e.g. a member of an `error_indicator` enumeration). ##### Example @@ -16706,27 +16706,27 @@ A not uncommon technique is to gather cleanup at the end of the function to avoi } The larger the function, the more tempting this technique becomes. -`finally` can [ease the pain a bit](#Re-finally). +`finally` can [ease the pain a bit](#re-finally). Also, the larger the program becomes the harder it is to apply an error-indicator-based error-handling strategy systematically. -We [prefer exception-based error handling](#Re-throw) and recommend [keeping functions short](#Rf-single). +We [prefer exception-based error handling](#re-throw) and recommend [keeping functions short](#rf-single). -**See also**: [Discussion](#Sd-???) +**See also**: [Discussion](#sd-???) -**See also**: [Returning multiple values](#Rf-out-multi) +**See also**: [Returning multiple values](#rf-out-multi) ##### Enforcement Awkward. -### E.28: Avoid error handling based on global state (e.g. `errno`) +### E.28: Avoid error handling based on global state (e.g. `errno`) ##### Reason Global state is hard to manage and it is easy to forget to check it. When did you last test the return value of `printf()`? -**See also**: [Simulating RAII](#Re-no-throw-raii) +**See also**: [Simulating RAII](#re-no-throw-raii) ##### Example, bad @@ -16749,7 +16749,7 @@ C-style error handling is based on the global variable `errno`, so it is essenti Awkward. -### E.30: Don't use exception specifications +### E.30: Don't use exception specifications ##### Reason @@ -16788,13 +16788,13 @@ For example, see [Stroustrup94](#Stroustrup94). ##### Note -If no exception can be thrown, use [`noexcept`](#Re-noexcept). +If no exception can be thrown, use [`noexcept`](#re-noexcept). ##### Enforcement Flag every exception specification. -### E.31: Properly order your `catch`-clauses +### E.31: Properly order your `catch`-clauses ##### Reason @@ -16821,7 +16821,7 @@ The "catch everything" handler ensured that the `std::exception`-handler will ne Flag all "hiding handlers". -# Con: Constants and immutability +# Con: Constants and immutability You can't have a race condition on a constant. It is easier to reason about a program when many of the objects cannot change their values. @@ -16829,13 +16829,13 @@ Interfaces that promise "no change" of objects passed as arguments greatly incre Constant rule summary: -* [Con.1: By default, make objects immutable](#Rconst-immutable) -* [Con.2: By default, make member functions `const`](#Rconst-fct) -* [Con.3: By default, pass pointers and references to `const`s](#Rconst-ref) -* [Con.4: Use `const` to define objects with values that do not change after construction](#Rconst-const) -* [Con.5: Use `constexpr` for values that can be computed at compile time](#Rconst-constexpr) +* [Con.1: By default, make objects immutable](#rconst-immutable) +* [Con.2: By default, make member functions `const`](#rconst-fct) +* [Con.3: By default, pass pointers and references to `const`s](#rconst-ref) +* [Con.4: Use `const` to define objects with values that do not change after construction](#rconst-const) +* [Con.5: Use `constexpr` for values that can be computed at compile time](#rconst-constexpr) -### Con.1: By default, make objects immutable +### Con.1: By default, make objects immutable ##### Reason @@ -16871,7 +16871,7 @@ Note that a function parameter is a local variable so changes to it are local. * Flag non-`const` variables that are not modified (except for parameters to avoid many false positives and returned local variables) -### Con.2: By default, make member functions `const` +### Con.2: By default, make member functions `const` ##### Reason @@ -16907,7 +16907,7 @@ This is a problem for people modernizing code. You can * update the library to be `const`-correct; preferred long-term solution -* "cast away `const`"; [best avoided](#Res-casts-const) +* "cast away `const`"; [best avoided](#res-casts-const) * provide a wrapper function Example: @@ -16945,13 +16945,13 @@ through non-`const` pointers. It is the job of the class to ensure such mutation is done only when it makes sense according to the semantics (invariants) it offers to its users. -**See also**: [Pimpl](#Ri-pimpl) +**See also**: [Pimpl](#ri-pimpl) ##### Enforcement * Flag a member function that is not marked `const`, but that does not perform a non-`const` operation on any data member. -### Con.3: By default, pass pointers and references to `const`s +### Con.3: By default, pass pointers and references to `const`s ##### Reason @@ -16970,14 +16970,14 @@ but that should be done only when the called function is supposed to modify the ##### Note -[Do not cast away `const`](#Res-casts-const). +[Do not cast away `const`](#res-casts-const). ##### Enforcement * Flag a function that does not modify an object passed by pointer or reference to non-`const` * Flag a function that (using a cast) modifies an object passed by pointer or reference to `const` -### Con.4: Use `const` to define objects with values that do not change after construction +### Con.4: Use `const` to define objects with values that do not change after construction ##### Reason @@ -17002,7 +17002,7 @@ As `x` is not `const`, we must assume that it is modified somewhere in the loop. * Flag unmodified non-`const` variables. -### Con.5: Use `constexpr` for values that can be computed at compile time +### Con.5: Use `constexpr` for values that can be computed at compile time ##### Reason @@ -17022,7 +17022,7 @@ See F.4. * Flag `const` definitions with constant expression initializers. -# T: Templates and generic programming +# T: Templates and generic programming Generic programming is programming using types and algorithms parameterized by types, values, and algorithms. In C++, generic programming is supported by the `template` language mechanisms. @@ -17037,98 +17037,98 @@ A central notion in generic programming is "concepts"; that is, requirements on Template use rule summary: -* [T.1: Use templates to raise the level of abstraction of code](#Rt-raise) -* [T.2: Use templates to express algorithms that apply to many argument types](#Rt-algo) -* [T.3: Use templates to express containers and ranges](#Rt-cont) -* [T.4: Use templates to express syntax tree manipulation](#Rt-expr) -* [T.5: Combine generic and OO techniques to amplify their strengths, not their costs](#Rt-generic-oo) +* [T.1: Use templates to raise the level of abstraction of code](#rt-raise) +* [T.2: Use templates to express algorithms that apply to many argument types](#rt-algo) +* [T.3: Use templates to express containers and ranges](#rt-cont) +* [T.4: Use templates to express syntax tree manipulation](#rt-expr) +* [T.5: Combine generic and OO techniques to amplify their strengths, not their costs](#rt-generic-oo) Concept use rule summary: -* [T.10: Specify concepts for all template arguments](#Rt-concepts) -* [T.11: Whenever possible use standard concepts](#Rt-std-concepts) -* [T.12: Prefer concept names over `auto` for local variables](#Rt-auto) -* [T.13: Prefer the shorthand notation for simple, single-type argument concepts](#Rt-shorthand) +* [T.10: Specify concepts for all template arguments](#rt-concepts) +* [T.11: Whenever possible use standard concepts](#rt-std-concepts) +* [T.12: Prefer concept names over `auto` for local variables](#rt-auto) +* [T.13: Prefer the shorthand notation for simple, single-type argument concepts](#rt-shorthand) * ??? Concept definition rule summary: -* [T.20: Avoid "concepts" without meaningful semantics](#Rt-low) -* [T.21: Require a complete set of operations for a concept](#Rt-complete) -* [T.22: Specify axioms for concepts](#Rt-axiom) -* [T.23: Differentiate a refined concept from its more general case by adding new use patterns](#Rt-refine) -* [T.24: Use tag classes or traits to differentiate concepts that differ only in semantics](#Rt-tag) -* [T.25: Avoid complementary constraints](#Rt-not) -* [T.26: Prefer to define concepts in terms of use-patterns rather than simple syntax](#Rt-use) -* [T.30: Use concept negation (`!C`) sparingly to express a minor difference](#Rt-???) -* [T.31: Use concept disjunction (`C1 || C2`) sparingly to express alternatives](#Rt-???) +* [T.20: Avoid "concepts" without meaningful semantics](#rt-low) +* [T.21: Require a complete set of operations for a concept](#rt-complete) +* [T.22: Specify axioms for concepts](#rt-axiom) +* [T.23: Differentiate a refined concept from its more general case by adding new use patterns](#rt-refine) +* [T.24: Use tag classes or traits to differentiate concepts that differ only in semantics](#rt-tag) +* [T.25: Avoid complementary constraints](#rt-not) +* [T.26: Prefer to define concepts in terms of use-patterns rather than simple syntax](#rt-use) +* [T.30: Use concept negation (`!C`) sparingly to express a minor difference](#rt-???) +* [T.31: Use concept disjunction (`C1 || C2`) sparingly to express alternatives](#rt-???) * ??? Template interface rule summary: -* [T.40: Use function objects to pass operations to algorithms](#Rt-fo) -* [T.41: Require only essential properties in a template's concepts](#Rt-essential) -* [T.42: Use template aliases to simplify notation and hide implementation details](#Rt-alias) -* [T.43: Prefer `using` over `typedef` for defining aliases](#Rt-using) -* [T.44: Use function templates to deduce class template argument types (where feasible)](#Rt-deduce) -* [T.46: Require template arguments to be at least semiregular](#Rt-regular) -* [T.47: Avoid highly visible unconstrained templates with common names](#Rt-visible) -* [T.48: If your compiler does not support concepts, fake them with `enable_if`](#Rt-concept-def) -* [T.49: Where possible, avoid type-erasure](#Rt-erasure) +* [T.40: Use function objects to pass operations to algorithms](#rt-fo) +* [T.41: Require only essential properties in a template's concepts](#rt-essential) +* [T.42: Use template aliases to simplify notation and hide implementation details](#rt-alias) +* [T.43: Prefer `using` over `typedef` for defining aliases](#rt-using) +* [T.44: Use function templates to deduce class template argument types (where feasible)](#rt-deduce) +* [T.46: Require template arguments to be at least semiregular](#rt-regular) +* [T.47: Avoid highly visible unconstrained templates with common names](#rt-visible) +* [T.48: If your compiler does not support concepts, fake them with `enable_if`](#rt-concept-def) +* [T.49: Where possible, avoid type-erasure](#rt-erasure) Template definition rule summary: -* [T.60: Minimize a template's context dependencies](#Rt-depend) -* [T.61: Do not over-parameterize members (SCARY)](#Rt-scary) -* [T.62: Place non-dependent class template members in a non-templated base class](#Rt-nondependent) -* [T.64: Use specialization to provide alternative implementations of class templates](#Rt-specialization) -* [T.65: Use tag dispatch to provide alternative implementations of functions](#Rt-tag-dispatch) -* [T.67: Use specialization to provide alternative implementations for irregular types](#Rt-specialization2) -* [T.68: Use `{}` rather than `()` within templates to avoid ambiguities](#Rt-cast) -* [T.69: Inside a template, don't make an unqualified non-member function call unless you intend it to be a customization point](#Rt-customization) +* [T.60: Minimize a template's context dependencies](#rt-depend) +* [T.61: Do not over-parameterize members (SCARY)](#rt-scary) +* [T.62: Place non-dependent class template members in a non-templated base class](#rt-nondependent) +* [T.64: Use specialization to provide alternative implementations of class templates](#rt-specialization) +* [T.65: Use tag dispatch to provide alternative implementations of functions](#rt-tag-dispatch) +* [T.67: Use specialization to provide alternative implementations for irregular types](#rt-specialization2) +* [T.68: Use `{}` rather than `()` within templates to avoid ambiguities](#rt-cast) +* [T.69: Inside a template, don't make an unqualified non-member function call unless you intend it to be a customization point](#rt-customization) Template and hierarchy rule summary: -* [T.80: Do not naively templatize a class hierarchy](#Rt-hier) -* [T.81: Do not mix hierarchies and arrays](#Rt-array) // ??? somewhere in "hierarchies" -* [T.82: Linearize a hierarchy when virtual functions are undesirable](#Rt-linear) -* [T.83: Do not declare a member function template virtual](#Rt-virtual) -* [T.84: Use a non-template core implementation to provide an ABI-stable interface](#Rt-abi) -* [T.??: ????](#Rt-???) +* [T.80: Do not naively templatize a class hierarchy](#rt-hier) +* [T.81: Do not mix hierarchies and arrays](#rt-array) // ??? somewhere in "hierarchies" +* [T.82: Linearize a hierarchy when virtual functions are undesirable](#rt-linear) +* [T.83: Do not declare a member function template virtual](#rt-virtual) +* [T.84: Use a non-template core implementation to provide an ABI-stable interface](#rt-abi) +* [T.??: ????](#rt-???) Variadic template rule summary: -* [T.100: Use variadic templates when you need a function that takes a variable number of arguments of a variety of types](#Rt-variadic) -* [T.101: ??? How to pass arguments to a variadic template ???](#Rt-variadic-pass) -* [T.102: ??? How to process arguments to a variadic template ???](#Rt-variadic-process) -* [T.103: Don't use variadic templates for homogeneous argument lists](#Rt-variadic-not) -* [T.??: ????](#Rt-???) +* [T.100: Use variadic templates when you need a function that takes a variable number of arguments of a variety of types](#rt-variadic) +* [T.101: ??? How to pass arguments to a variadic template ???](#rt-variadic-pass) +* [T.102: ??? How to process arguments to a variadic template ???](#rt-variadic-process) +* [T.103: Don't use variadic templates for homogeneous argument lists](#rt-variadic-not) +* [T.??: ????](#rt-???) Metaprogramming rule summary: -* [T.120: Use template metaprogramming only when you really need to](#Rt-metameta) -* [T.121: Use template metaprogramming primarily to emulate concepts](#Rt-emulate) -* [T.122: Use templates (usually template aliases) to compute types at compile time](#Rt-tmp) -* [T.123: Use `constexpr` functions to compute values at compile time](#Rt-fct) -* [T.124: Prefer to use standard-library TMP facilities](#Rt-std-tmp) -* [T.125: If you need to go beyond the standard-library TMP facilities, use an existing library](#Rt-lib) -* [T.??: ????](#Rt-???) +* [T.120: Use template metaprogramming only when you really need to](#rt-metameta) +* [T.121: Use template metaprogramming primarily to emulate concepts](#rt-emulate) +* [T.122: Use templates (usually template aliases) to compute types at compile time](#rt-tmp) +* [T.123: Use `constexpr` functions to compute values at compile time](#rt-fct) +* [T.124: Prefer to use standard-library TMP facilities](#rt-std-tmp) +* [T.125: If you need to go beyond the standard-library TMP facilities, use an existing library](#rt-lib) +* [T.??: ????](#rt-???) Other template rules summary: -* [T.140: If an operation can be reused, give it a name](#Rt-name) -* [T.141: Use an unnamed lambda if you need a simple function object in one place only](#Rt-lambda) -* [T.142: Use template variables to simplify notation](#Rt-var) -* [T.143: Don't write unintentionally non-generic code](#Rt-non-generic) -* [T.144: Don't specialize function templates](#Rt-specialize-function) -* [T.150: Check that a class matches a concept using `static_assert`](#Rt-check-class) -* [T.??: ????](#Rt-???) +* [T.140: If an operation can be reused, give it a name](#rt-name) +* [T.141: Use an unnamed lambda if you need a simple function object in one place only](#rt-lambda) +* [T.142: Use template variables to simplify notation](#rt-var) +* [T.143: Don't write unintentionally non-generic code](#rt-non-generic) +* [T.144: Don't specialize function templates](#rt-specialize-function) +* [T.150: Check that a class matches a concept using `static_assert`](#rt-check-class) +* [T.??: ????](#rt-???) -## T.gp: Generic programming +## T.gp: Generic programming Generic programming is programming using types and algorithms parameterized by types, values, and algorithms. -### T.1: Use templates to raise the level of abstraction of code +### T.1: Use templates to raise the level of abstraction of code ##### Reason @@ -17189,7 +17189,7 @@ is to efficiently generalize operations/algorithms over a set of types with simi * Flag algorithms with "overly simple" requirements, such as direct use of specific operators without a concept. * Do not flag the definition of the "overly simple" concepts themselves; they might simply be building blocks for more useful concepts. -### T.2: Use templates to express algorithms that apply to many argument types +### T.2: Use templates to express algorithms that apply to many argument types ##### Reason @@ -17216,7 +17216,7 @@ Don't overabstract. ??? tough, probably needs a human -### T.3: Use templates to express containers and ranges +### T.3: Use templates to express containers and ranges ##### Reason @@ -17252,13 +17252,13 @@ This doesn't directly express the intent of the programmer and hides the structu Hiding the `void*` behind macros simply obscures the problems and introduces new opportunities for confusion. **Exceptions**: If you need an ABI-stable interface, you might have to provide a base implementation and express the (type-safe) template in terms of that. -See [Stable base](#Rt-abi). +See [Stable base](#rt-abi). ##### Enforcement * Flag uses of `void*`s and casts outside low-level implementation code -### T.4: Use templates to express syntax tree manipulation +### T.4: Use templates to express syntax tree manipulation ##### Reason @@ -17270,7 +17270,7 @@ See [Stable base](#Rt-abi). **Exceptions**: ??? -### T.5: Combine generic and OO techniques to amplify their strengths, not their costs +### T.5: Combine generic and OO techniques to amplify their strengths, not their costs ##### Reason @@ -17293,7 +17293,7 @@ Static helps dynamic: Use static polymorphism to implement dynamically polymorph ##### Example Dynamic helps static: Offer a generic, comfortable, statically bound interface, but internally dispatch dynamically, so you offer a uniform object layout. -Examples include type erasure as with `std::shared_ptr`'s deleter (but [don't overuse type erasure](#Rt-erasure)). +Examples include type erasure as with `std::shared_ptr`'s deleter (but [don't overuse type erasure](#rt-erasure)). #include @@ -17352,7 +17352,7 @@ Avoid this, even though the standard-library facets made this mistake. See the reference to more specific rules. -## T.concepts: Concept rules +## T.concepts: Concept rules Concepts is a C++20 facility for specifying requirements for template arguments. They are crucial in the thinking about generic programming and the basis of much work on future C++ libraries @@ -17362,26 +17362,26 @@ This section assumes concept support Concept use rule summary: -* [T.10: Specify concepts for all template arguments](#Rt-concepts) -* [T.11: Whenever possible use standard concepts](#Rt-std-concepts) -* [T.12: Prefer concept names over `auto`](#Rt-auto) -* [T.13: Prefer the shorthand notation for simple, single-type argument concepts](#Rt-shorthand) +* [T.10: Specify concepts for all template arguments](#rt-concepts) +* [T.11: Whenever possible use standard concepts](#rt-std-concepts) +* [T.12: Prefer concept names over `auto`](#rt-auto) +* [T.13: Prefer the shorthand notation for simple, single-type argument concepts](#rt-shorthand) * ??? Concept definition rule summary: -* [T.20: Avoid "concepts" without meaningful semantics](#Rt-low) -* [T.21: Require a complete set of operations for a concept](#Rt-complete) -* [T.22: Specify axioms for concepts](#Rt-axiom) -* [T.23: Differentiate a refined concept from its more general case by adding new use patterns](#Rt-refine) -* [T.24: Use tag classes or traits to differentiate concepts that differ only in semantics](#Rt-tag) -* [T.25: Avoid complimentary constraints](#Rt-not) -* [T.26: Prefer to define concepts in terms of use-patterns rather than simple syntax](#Rt-use) +* [T.20: Avoid "concepts" without meaningful semantics](#rt-low) +* [T.21: Require a complete set of operations for a concept](#rt-complete) +* [T.22: Specify axioms for concepts](#rt-axiom) +* [T.23: Differentiate a refined concept from its more general case by adding new use patterns](#rt-refine) +* [T.24: Use tag classes or traits to differentiate concepts that differ only in semantics](#rt-tag) +* [T.25: Avoid complimentary constraints](#rt-not) +* [T.26: Prefer to define concepts in terms of use-patterns rather than simple syntax](#rt-use) * ??? -## T.con-use: Concept use +## T.con-use: Concept use -### T.10: Specify concepts for all template arguments +### T.10: Specify concepts for all template arguments ##### Reason @@ -17421,7 +17421,7 @@ This is typically only needed when (as part of template metaprogramming code) we Flag template type arguments without concepts -### T.11: Whenever possible use standard concepts +### T.11: Whenever possible use standard concepts ##### Reason @@ -17461,7 +17461,7 @@ Hard. * Look for unconstrained arguments, templates that use "unusual"/non-standard concepts, templates that use "homebrew" concepts without axioms. * Develop a concept-discovery tool (e.g., see [an early experiment](http://www.stroustrup.com/sle2010_webversion.pdf)). -### T.12: Prefer concept names over `auto` for local variables +### T.12: Prefer concept names over `auto` for local variables ##### Reason @@ -17477,7 +17477,7 @@ Hard. * ??? -### T.13: Prefer the shorthand notation for simple, single-type argument concepts +### T.13: Prefer the shorthand notation for simple, single-type argument concepts ##### Reason @@ -17503,7 +17503,7 @@ The shorter versions better match the way we speak. Note that many templates don * Not feasible in the short term when people convert from the `` and ` notation. * Later, flag declarations that first introduce a typename and then constrain it with a simple, single-type-argument concept. -## T.concepts.def: Concept definition rules +## T.concepts.def: Concept definition rules Defining good concepts is non-trivial. Concepts are meant to represent fundamental concepts in an application domain (hence the name "concepts"). @@ -17513,7 +17513,7 @@ and will not give the full benefits of the mechanism. Obviously, defining concepts is most useful for code that can use an implementation (e.g., C++20 or later) but defining concepts is in itself a useful design technique and helps catch conceptual errors and clean up the concepts (sic!) of an implementation. -### T.20: Avoid "concepts" without meaningful semantics +### T.20: Avoid "concepts" without meaningful semantics ##### Reason @@ -17580,7 +17580,7 @@ Concepts with multiple operations have far lower chance of accidentally matching * Flag uses of `enable_if` that appear to simulate single-operation `concepts`. -### T.21: Require a complete set of operations for a concept +### T.21: Require a complete set of operations for a concept ##### Reason @@ -17590,7 +17590,7 @@ Helps implementers and maintainers. ##### Note -This is a specific variant of the general rule that [a concept must make semantic sense](#Rt-low). +This is a specific variant of the general rule that [a concept must make semantic sense](#rt-low). ##### Example, bad @@ -17670,7 +17670,7 @@ Ideally, that rule should be language supported by giving you comparison operato Yes, `std::string` is "odd", but it's too late to change that. -### T.22: Specify axioms for concepts +### T.22: Specify axioms for concepts ##### Reason @@ -17699,7 +17699,7 @@ An axiom might not be general, but the template writer can assume that it holds ##### Note In this context axioms are Boolean expressions. -See the [Palo Alto TR](#S-references) for examples. +See the [Palo Alto TR](#s-references) for examples. Currently, C++ does not support axioms (even the ISO Concepts TS), so we have to make do with comments for a longish while. Once language support is available, the `//` in front of the axiom can be removed @@ -17733,7 +17733,7 @@ Each new use case might require such an incomplete concept to be improved. * Look for the word "axiom" in concept definition comments -### T.23: Differentiate a refined concept from its more general case by adding new use patterns. +### T.23: Differentiate a refined concept from its more general case by adding new use patterns. ##### Reason @@ -17757,9 +17757,9 @@ If two concepts have exactly the same requirements, they are logically equivalen ##### Enforcement * Flag a concept that has exactly the same requirements as another already-seen concept (neither is more refined). -To disambiguate them, see [T.24](#Rt-tag). +To disambiguate them, see [T.24](#rt-tag). -### T.24: Use tag classes or traits to differentiate concepts that differ only in semantics. +### T.24: Use tag classes or traits to differentiate concepts that differ only in semantics. ##### Reason @@ -17798,7 +17798,7 @@ Prefer the standard-library ones. * The compiler flags ambiguous use of identical concepts. * Flag the definition of identical concepts. -### T.25: Avoid complementary constraints +### T.25: Avoid complementary constraints ##### Reason @@ -17864,7 +17864,7 @@ Now the opportunities for errors multiply. * Flag pairs of functions with `C` and `!C` constraints -### T.26: Prefer to define concepts in terms of use-patterns rather than simple syntax +### T.26: Prefer to define concepts in terms of use-patterns rather than simple syntax ##### Reason @@ -17894,14 +17894,14 @@ By "meaningless" we mean that we cannot specify the semantics of `has_equal` in ??? -## Template interfaces +## Template interfaces Over the years, programming with templates has suffered from a weak distinction between the interface of a template and its implementation. Before concepts, that distinction had no direct language support. However, the interface to a template is a critical concept - a contract between a user and an implementer - and should be carefully designed. -### T.40: Use function objects to pass operations to algorithms +### T.40: Use function objects to pass operations to algorithms ##### Reason @@ -17939,7 +17939,7 @@ The performance argument depends on compiler and optimizer technology. * Flag pointers to functions passed as arguments to a template (risk of false positives). -### T.41: Require only essential properties in a template's concepts +### T.41: Require only essential properties in a template's concepts ##### Reason @@ -17994,7 +17994,7 @@ It can be hard to decide which properties of a type are essential and which are ??? -### T.42: Use template aliases to simplify notation and hide implementation details +### T.42: Use template aliases to simplify notation and hide implementation details ##### Reason @@ -18047,7 +18047,7 @@ A simple, common use could be expressed: "Wrap traits!" * Flag use of `typename` as a disambiguator outside `using` declarations. * ??? -### T.43: Prefer `using` over `typedef` for defining aliases +### T.43: Prefer `using` over `typedef` for defining aliases ##### Reason @@ -18071,7 +18071,7 @@ Uniformity: `using` is syntactically similar to `auto`. * Flag uses of `typedef`. This will give a lot of "hits" :-( -### T.44: Use function templates to deduce class template argument types (where feasible) +### T.44: Use function templates to deduce class template argument types (where feasible) ##### Reason @@ -18107,7 +18107,7 @@ For example: Flag uses where an explicitly specialized type exactly matches the types of the arguments used. -### T.46: Require template arguments to be at least semiregular +### T.46: Require template arguments to be at least semiregular ##### Reason @@ -18140,7 +18140,7 @@ Semiregular requires default constructible. * Flag types used as template arguments that are not at least semiregular. -### T.47: Avoid highly visible unconstrained templates with common names +### T.47: Avoid highly visible unconstrained templates with common names ##### Reason @@ -18193,7 +18193,7 @@ Unfortunately this will get many false positives; the standard library violates Flag templates defined in a namespace where concrete types are also defined (maybe not feasible until we have concepts). -### T.48: If your compiler does not support concepts, fake them with `enable_if` +### T.48: If your compiler does not support concepts, fake them with `enable_if` ##### Reason @@ -18218,14 +18218,14 @@ Because that's the best we can do without direct concept support. ##### Note -Beware of [complementary constraints](#Rt-not). +Beware of [complementary constraints](#rt-not). Faking concept overloading using `enable_if` sometimes forces us to use that error-prone design technique. ##### Enforcement ??? -### T.49: Where possible, avoid type-erasure +### T.49: Where possible, avoid type-erasure ##### Reason @@ -18245,13 +18245,13 @@ Type erasure incurs an extra level of indirection by hiding type information beh ##### Note -## T.def: Template definitions +## T.def: Template definitions A template definition (class or function) can contain arbitrary code, so only a comprehensive review of C++ programming techniques would cover this topic. However, this section focuses on what is specific to template implementation. In particular, it focuses on a template definition's dependence on its context. -### T.60: Minimize a template's context dependencies +### T.60: Minimize a template's context dependencies ##### Reason @@ -18288,13 +18288,13 @@ Having a template operate only on its arguments would be one way of reducing the For example, algorithms usually use other algorithms and invoke operations that do not exclusively operate on arguments. And don't get us started on macros! -**See also**: [T.69](#Rt-customization) +**See also**: [T.69](#rt-customization) ##### Enforcement ??? Tricky -### T.61: Do not over-parameterize members (SCARY) +### T.61: Do not over-parameterize members (SCARY) ##### Reason @@ -18365,7 +18365,7 @@ This also applies to lambdas that don't depend on all of the template parameters * Flag member functions that do not depend on every template parameter * Flag lambdas or variable templates that do not depend on every template parameter -### T.62: Place non-dependent class template members in a non-templated base class +### T.62: Place non-dependent class template members in a non-templated base class ##### Reason @@ -18397,7 +18397,7 @@ This also applies to lambdas that don't depend on all of the template parameters A more general version of this rule would be "If a class template member depends on only N template parameters out of M, place it in a base class with only N parameters." -For N == 1, we have a choice of a base class of a class in the surrounding scope as in [T.61](#Rt-scary). +For N == 1, we have a choice of a base class of a class in the surrounding scope as in [T.61](#rt-scary). ??? What about constants? class statics? @@ -18405,7 +18405,7 @@ For N == 1, we have a choice of a base class of a class in the surrounding scope * Flag ??? -### T.64: Use specialization to provide alternative implementations of class templates +### T.64: Use specialization to provide alternative implementations of class templates ##### Reason @@ -18426,7 +18426,7 @@ Specialization offers a powerful mechanism for providing alternative implementat ??? -### T.65: Use tag dispatch to provide alternative implementations of a function +### T.65: Use tag dispatch to provide alternative implementations of a function ##### Reason @@ -18495,7 +18495,7 @@ With C++20 constraints, such alternatives can be distinguished directly: ??? -### T.67: Use specialization to provide alternative implementations for irregular types +### T.67: Use specialization to provide alternative implementations for irregular types ##### Reason @@ -18509,7 +18509,7 @@ With C++20 constraints, such alternatives can be distinguished directly: ??? -### T.68: Use `{}` rather than `()` within templates to avoid ambiguities +### T.68: Use `{}` rather than `()` within templates to avoid ambiguities ##### Reason @@ -18533,7 +18533,7 @@ With C++20 constraints, such alternatives can be distinguished directly: * flag function-style casts -### T.69: Inside a template, don't make an unqualified non-member function call unless you intend it to be a customization point +### T.69: Inside a template, don't make an unqualified non-member function call unless you intend it to be a customization point ##### Reason @@ -18575,7 +18575,7 @@ or a traditional traits template to be specialized on the user's type. If you intend to call your own helper function `helper(t)` with a value `t` that depends on a template type parameter, put it in a `::detail` namespace and qualify the call as `detail::helper(t);`. An unqualified call becomes a customization point where any function `helper` in the namespace of `t`'s type can be invoked; -this can cause problems like [unintentionally invoking unconstrained function templates](#Rt-visible). +this can cause problems like [unintentionally invoking unconstrained function templates](#rt-visible). ##### Enforcement @@ -18583,13 +18583,13 @@ this can cause problems like [unintentionally invoking unconstrained function te * In a template, flag an unqualified call to a non-member function that passes a variable of dependent type when there is a non-member function of the same name in the template's namespace. -## T.temp-hier: Template and hierarchy rules: +## T.temp-hier: Template and hierarchy rules: Templates are the backbone of C++'s support for generic programming and class hierarchies the backbone of its support for object-oriented programming. The two language mechanisms can be used effectively in combination, but a few design pitfalls must be avoided. -### T.80: Do not naively templatize a class hierarchy +### T.80: Do not naively templatize a class hierarchy ##### Reason @@ -18624,13 +18624,13 @@ Imagine what this would do to a class hierarchy with dozens of member functions ##### Note In many cases you can provide a stable interface by not parameterizing a base; -see ["stable base"](#Rt-abi) and [OO and GP](#Rt-generic-oo) +see ["stable base"](#rt-abi) and [OO and GP](#rt-generic-oo) ##### Enforcement * Flag virtual functions that depend on a template argument. ??? False positives -### T.81: Do not mix hierarchies and arrays +### T.81: Do not mix hierarchies and arrays ##### Reason @@ -18657,7 +18657,7 @@ If `sizeof(Apple) != sizeof(Pear)` the access to `aa[1]` will not be aligned to We have a type violation and possibly (probably) a memory corruption. Never write such code. -Note that `maul()` violates the a [`T*` points to an individual object rule](#Rf-ptr). +Note that `maul()` violates the a [`T*` points to an individual object rule](#rf-ptr). **Alternative**: Use a proper (templatized) container: @@ -18673,13 +18673,13 @@ Note that `maul()` violates the a [`T*` points to an individual object rule](#Rf Apple& a0 = &va[0]; // a Pear? -Note that the assignment in `maul2()` violated the [no-slicing rule](#Res-slice). +Note that the assignment in `maul2()` violated the [no-slicing rule](#res-slice). ##### Enforcement * Detect this horror! -### T.82: Linearize a hierarchy when virtual functions are undesirable +### T.82: Linearize a hierarchy when virtual functions are undesirable ##### Reason @@ -18693,7 +18693,7 @@ Note that the assignment in `maul2()` violated the [no-slicing rule](#Res-slice) ??? -### T.83: Do not declare a member function template virtual +### T.83: Do not declare a member function template virtual ##### Reason @@ -18721,7 +18721,7 @@ Double dispatch, visitors, calculate which function to call The compiler handles that. -### T.84: Use a non-template core implementation to provide an ABI-stable interface +### T.84: Use a non-template core implementation to provide an ABI-stable interface ##### Reason @@ -18765,17 +18765,17 @@ The `Link` and `List` classes do nothing but type manipulation. Instead of using a separate "base" type, another common technique is to specialize for `void` or `void*` and have the general template for `T` be just the safely-encapsulated casts to and from the core `void` implementation. -**Alternative**: Use a [Pimpl](#Ri-pimpl) implementation. +**Alternative**: Use a [Pimpl](#ri-pimpl) implementation. ##### Enforcement ??? -## T.var: Variadic template rules +## T.var: Variadic template rules ??? -### T.100: Use variadic templates when you need a function that takes a variable number of arguments of a variety of types +### T.100: Use variadic templates when you need a function that takes a variable number of arguments of a variety of types ##### Reason @@ -18789,7 +18789,7 @@ Variadic templates is the most general mechanism for that, and is both efficient * Flag uses of `va_arg` in user code. -### T.101: ??? How to pass arguments to a variadic template ??? +### T.101: ??? How to pass arguments to a variadic template ??? ##### Reason @@ -18803,7 +18803,7 @@ Variadic templates is the most general mechanism for that, and is both efficient ??? -### T.102: How to process arguments to a variadic template +### T.102: How to process arguments to a variadic template ##### Reason @@ -18817,7 +18817,7 @@ Variadic templates is the most general mechanism for that, and is both efficient ??? -### T.103: Don't use variadic templates for homogeneous argument lists +### T.103: Don't use variadic templates for homogeneous argument lists ##### Reason @@ -18831,7 +18831,7 @@ There are more precise ways of specifying a homogeneous sequence, such as an `in ??? -## T.meta: Template metaprogramming (TMP) +## T.meta: Template metaprogramming (TMP) Templates provide a general mechanism for compile-time programming. @@ -18839,7 +18839,7 @@ Metaprogramming is programming where at least one input or one result is a type. Templates offer Turing-complete (modulo memory capacity) duck typing at compile time. The syntax and techniques needed are pretty horrendous. -### T.120: Use template metaprogramming only when you really need to +### T.120: Use template metaprogramming only when you really need to ##### Reason @@ -18856,19 +18856,19 @@ For example, if you really need AST manipulation at compile time (e.g., for opti enable_if -Instead, use concepts. But see [How to emulate concepts if you don't have language support](#Rt-emulate). +Instead, use concepts. But see [How to emulate concepts if you don't have language support](#rt-emulate). ##### Example ??? good -**Alternative**: If the result is a value, rather than a type, use a [`constexpr` function](#Rt-fct). +**Alternative**: If the result is a value, rather than a type, use a [`constexpr` function](#rt-fct). ##### Note If you feel the need to hide your template metaprogramming in macros, you have probably gone too far. -### T.121: Use template metaprogramming primarily to emulate concepts +### T.121: Use template metaprogramming primarily to emulate concepts ##### Reason @@ -18897,7 +18897,7 @@ Such code is much simpler using concepts: ??? -### T.122: Use templates (usually template aliases) to compute types at compile time +### T.122: Use templates (usually template aliases) to compute types at compile time ##### Reason @@ -18915,7 +18915,7 @@ Template metaprogramming is the only directly supported and half-way principled ??? -### T.123: Use `constexpr` functions to compute values at compile time +### T.123: Use `constexpr` functions to compute values at compile time ##### Reason @@ -18943,7 +18943,7 @@ Often a `constexpr` function implies less compile-time overhead than alternative * Flag template metaprograms yielding a value. These should be replaced with `constexpr` functions. -### T.124: Prefer to use standard-library TMP facilities +### T.124: Prefer to use standard-library TMP facilities ##### Reason @@ -18957,7 +18957,7 @@ Facilities defined in the standard, such as `conditional`, `enable_if`, and `tup ??? -### T.125: If you need to go beyond the standard-library TMP facilities, use an existing library +### T.125: If you need to go beyond the standard-library TMP facilities, use an existing library ##### Reason @@ -18972,17 +18972,17 @@ Write your own "advanced TMP support" only if you really have to. ??? -## Other template rules +## Other template rules -### T.140: If an operation can be reused, give it a name +### T.140: If an operation can be reused, give it a name -See [F.10](#Rf-name) +See [F.10](#rf-name) -### T.141: Use an unnamed lambda if you need a simple function object in one place only +### T.141: Use an unnamed lambda if you need a simple function object in one place only -See [F.11](#Rf-lambda) +See [F.11](#rf-lambda) -### T.142?: Use template variables to simplify notation +### T.142?: Use template variables to simplify notation ##### Reason @@ -18996,7 +18996,7 @@ Improved readability. ??? -### T.143: Don't write unintentionally non-generic code +### T.143: Don't write unintentionally non-generic code ##### Reason @@ -19056,7 +19056,7 @@ Use the least-derived class that has the functionality you need. * Flag `x.size() == 0` when `x.empty()` or `x.is_empty()` is available. Emptiness works for more containers than size(), because some containers don't know their size or are conceptually of unbounded size. * Flag functions that take a pointer or reference to a more-derived type but only use functions declared in a base type. -### T.144: Don't specialize function templates +### T.144: Don't specialize function templates ##### Reason @@ -19073,7 +19073,7 @@ You can't partially specialize a function template per language rules. You can f * Flag all specializations of a function template. Overload instead. -### T.150: Check that a class matches a concept using `static_assert` +### T.150: Check that a class matches a concept using `static_assert` ##### Reason @@ -19100,7 +19100,7 @@ Somewhere, possibly in an implementation file, let the compiler check the desire Not feasible. -# CPL: C-style programming +# CPL: C-style programming C and C++ are closely related languages. They both originate in "Classic C" from 1978 and have evolved in ISO committees since then. @@ -19108,11 +19108,11 @@ Many attempts have been made to keep them compatible, but neither is a subset of C rule summary: -* [CPL.1: Prefer C++ to C](#Rcpl-C) -* [CPL.2: If you must use C, use the common subset of C and C++, and compile the C code as C++](#Rcpl-subset) -* [CPL.3: If you must use C for interfaces, use C++ in the calling code using such interfaces](#Rcpl-interface) +* [CPL.1: Prefer C++ to C](#rcpl-c) +* [CPL.2: If you must use C, use the common subset of C and C++, and compile the C code as C++](#rcpl-subset) +* [CPL.3: If you must use C for interfaces, use C++ in the calling code using such interfaces](#rcpl-interface) -### CPL.1: Prefer C++ to C +### CPL.1: Prefer C++ to C ##### Reason @@ -19133,7 +19133,7 @@ In particular, this example violates a rule against converting to a type with st Use a C++ compiler. -### CPL.2: If you must use C, use the common subset of C and C++, and compile the C code as C++ +### CPL.2: If you must use C, use the common subset of C and C++, and compile the C code as C++ ##### Reason @@ -19152,7 +19152,7 @@ That subset can be compiled with both C and C++ compilers, and when compiled as * The C++ compiler will enforce that the code is valid C++ unless you use C extension options. -### CPL.3: If you must use C for interfaces, use C++ in the calling code using such interfaces +### CPL.3: If you must use C for interfaces, use C++ in the calling code using such interfaces ##### Reason @@ -19192,36 +19192,36 @@ You can call C++ from C: None needed -# SF: Source files +# SF: Source files Distinguish between declarations (used as interfaces) and definitions (used as implementations). Use header files to represent interfaces and to emphasize logical structure. Source file rule summary: -* [SF.1: Use a `.cpp` suffix for code files and `.h` for interface files if your project doesn't already follow another convention](#Rs-file-suffix) -* [SF.2: A header file must not contain object definitions or non-inline function definitions](#Rs-inline) -* [SF.3: Use header files for all declarations used in multiple source files](#Rs-declaration-header) -* [SF.4: Include header files before other declarations in a file](#Rs-include-order) -* [SF.5: A `.cpp` file must include the header file(s) that defines its interface](#Rs-consistency) -* [SF.6: Use `using namespace` directives for transition, for foundation libraries (such as `std`), or within a local scope (only)](#Rs-using) -* [SF.7: Don't write `using namespace` at global scope in a header file](#Rs-using-directive) -* [SF.8: Use `#include` guards for all header files](#Rs-guards) -* [SF.9: Avoid cyclic dependencies among source files](#Rs-cycles) -* [SF.10: Avoid dependencies on implicitly `#include`d names](#Rs-implicit) -* [SF.11: Header files should be self-contained](#Rs-contained) -* [SF.12: Prefer the quoted form of `#include` for files relative to the including file and the angle bracket form everywhere else](#Rs-incform) -* [SF.13: Use portable header identifiers in `#include` statements](#Rs-portable-header-id) +* [SF.1: Use a `.cpp` suffix for code files and `.h` for interface files if your project doesn't already follow another convention](#rs-file-suffix) +* [SF.2: A header file must not contain object definitions or non-inline function definitions](#rs-inline) +* [SF.3: Use header files for all declarations used in multiple source files](#rs-declaration-header) +* [SF.4: Include header files before other declarations in a file](#rs-include-order) +* [SF.5: A `.cpp` file must include the header file(s) that defines its interface](#rs-consistency) +* [SF.6: Use `using namespace` directives for transition, for foundation libraries (such as `std`), or within a local scope (only)](#rs-using) +* [SF.7: Don't write `using namespace` at global scope in a header file](#rs-using-directive) +* [SF.8: Use `#include` guards for all header files](#rs-guards) +* [SF.9: Avoid cyclic dependencies among source files](#rs-cycles) +* [SF.10: Avoid dependencies on implicitly `#include`d names](#rs-implicit) +* [SF.11: Header files should be self-contained](#rs-contained) +* [SF.12: Prefer the quoted form of `#include` for files relative to the including file and the angle bracket form everywhere else](#rs-incform) +* [SF.13: Use portable header identifiers in `#include` statements](#rs-portable-header-id) -* [SF.20: Use `namespace`s to express logical structure](#Rs-namespace) -* [SF.21: Don't use an unnamed (anonymous) namespace in a header](#Rs-unnamed) -* [SF.22: Use an unnamed (anonymous) namespace for all internal/non-exported entities](#Rs-unnamed2) +* [SF.20: Use `namespace`s to express logical structure](#rs-namespace) +* [SF.21: Don't use an unnamed (anonymous) namespace in a header](#rs-unnamed) +* [SF.22: Use an unnamed (anonymous) namespace for all internal/non-exported entities](#rs-unnamed2) -### SF.1: Use a `.cpp` suffix for code files and `.h` for interface files if your project doesn't already follow another convention +### SF.1: Use a `.cpp` suffix for code files and `.h` for interface files if your project doesn't already follow another convention -See [NL.27](#Rl-file-suffix) +See [NL.27](#rl-file-suffix) -### SF.2: A header file must not contain object definitions or non-inline function definitions +### SF.2: A header file must not contain object definitions or non-inline function definitions ##### Reason @@ -19262,7 +19262,7 @@ Linking `file1.cpp` and `file2.cpp` will give two linker errors. Check the positive list above. -### SF.3: Use header files for all declarations used in multiple source files +### SF.3: Use header files for all declarations used in multiple source files ##### Reason @@ -19284,7 +19284,7 @@ The user of `bar` cannot know if the interface used is complete and correct. At * Flag declarations of entities in other source files not placed in a `.h`. -### SF.4: Include header files before other declarations in a file +### SF.4: Include header files before other declarations in a file ##### Reason @@ -19330,7 +19330,7 @@ However Easy. -### SF.5: A `.cpp` file must include the header file(s) that defines its interface +### SF.5: A `.cpp` file must include the header file(s) that defines its interface ##### Reason @@ -19371,7 +19371,7 @@ The argument-type error for `bar` cannot be caught until link time because of th ??? -### SF.6: Use `using namespace` directives for transition, for foundation libraries (such as `std`), or within a local scope (only) +### SF.6: Use `using namespace` directives for transition, for foundation libraries (such as `std`), or within a local scope (only) ##### Reason @@ -19420,9 +19420,9 @@ and M functions each containing a `using namespace X` with N lines of code in to ##### Note -[Don't write `using namespace` at global scope in a header file](#Rs-using-directive). +[Don't write `using namespace` at global scope in a header file](#rs-using-directive). -### SF.7: Don't write `using namespace` at global scope in a header file +### SF.7: Don't write `using namespace` at global scope in a header file ##### Reason @@ -19454,7 +19454,7 @@ to name their own UDLs `operator""_x` - they will not collide with the standard Flag `using namespace` at global scope in a header file. -### SF.8: Use `#include` guards for all header files +### SF.8: Use `#include` guards for all header files ##### Reason @@ -19481,9 +19481,9 @@ Flag `.h` files without `#include` guards. Some implementations offer vendor extensions like `#pragma once` as alternative to include guards. It is not standard and it is not portable. It injects the hosting machine's filesystem semantics into your program, in addition to locking you down to a vendor. -Our recommendation is to write in ISO C++: See [rule P.2](#Rp-Cplusplus). +Our recommendation is to write in ISO C++: See [rule P.2](#rp-cplusplus). -### SF.9: Avoid cyclic dependencies among source files +### SF.9: Avoid cyclic dependencies among source files ##### Reason @@ -19511,7 +19511,7 @@ Eliminate cycles; don't just break them with `#include` guards. Flag all cycles. -### SF.10: Avoid dependencies on implicitly `#include`d names +### SF.10: Avoid dependencies on implicitly `#include`d names ##### Reason @@ -19581,7 +19581,7 @@ This rule against implicit inclusion is not meant to prevent such deliberate agg Enforcement would require some knowledge about what in a header is meant to be "exported" to users and what is there to enable implementation. No really good solution is possible until we have modules. -### SF.11: Header files should be self-contained +### SF.11: Header files should be self-contained ##### Reason @@ -19606,7 +19606,7 @@ A header should include all its dependencies. Be careful about using relative pa A test should verify that the header file itself compiles or that a cpp file which only includes the header file compiles. -### SF.12: Prefer the quoted form of `#include` for files relative to the including file and the angle bracket form everywhere else +### SF.12: Prefer the quoted form of `#include` for files relative to the including file and the angle bracket form everywhere else ##### Reason @@ -19635,7 +19635,7 @@ Library creators should put their headers in a folder and have clients include t A test should identify whether headers referenced via `""` could be referenced with `<>`. -### SF.13: Use portable header identifiers in `#include` statements +### SF.13: Use portable header identifiers in `#include` statements ##### Reason @@ -19663,7 +19663,7 @@ To maximize the portability of `#include` directives across compilers, guidance It is only possible to enforce on implementations where header identifiers are case-sensitive and which only support `/` as a file path delimiter. -### SF.20: Use `namespace`s to express logical structure +### SF.20: Use `namespace`s to express logical structure ##### Reason @@ -19677,7 +19677,7 @@ It is only possible to enforce on implementations where header identifiers are c ??? -### SF.21: Don't use an unnamed (anonymous) namespace in a header +### SF.21: Don't use an unnamed (anonymous) namespace in a header ##### Reason @@ -19710,7 +19710,7 @@ It is almost always a bug to mention an unnamed namespace in a header file. * Flag any use of an anonymous namespace in a header file. -### SF.22: Use an unnamed (anonymous) namespace for all internal/non-exported entities +### SF.22: Use an unnamed (anonymous) namespace for all internal/non-exported entities ##### Reason @@ -19743,7 +19743,7 @@ An API class and its members can't live in an unnamed namespace; but any "helper * ??? -# SL: The Standard Library +# SL: The Standard Library Using only the bare language, every task is tedious (in any language). Using a suitable library any task can be reasonably simple. @@ -19756,22 +19756,22 @@ So, it is likely that this library section of the guidelines will eventually gro C++ Standard Library component summary: -* [SL.con: Containers](#SS-con) -* [SL.str: String](#SS-string) -* [SL.io: Iostream](#SS-io) -* [SL.regex: Regex](#SS-regex) -* [SL.chrono: Time](#SS-chrono) -* [SL.C: The C Standard Library](#SS-clib) +* [SL.con: Containers](#ss-con) +* [SL.str: String](#ss-string) +* [SL.io: Iostream](#ss-io) +* [SL.regex: Regex](#ss-regex) +* [SL.chrono: Time](#ss-chrono) +* [SL.C: The C Standard Library](#ss-clib) Standard-library rule summary: -* [SL.1: Use libraries wherever possible](#Rsl-lib) -* [SL.2: Prefer the standard library to other libraries](#Rsl-sl) +* [SL.1: Use libraries wherever possible](#rsl-lib) +* [SL.2: Prefer the standard library to other libraries](#rsl-sl) * [SL.3: Do not add non-standard entities to namespace `std`](#sl-std) * [SL.4: Use the standard library in a type-safe manner](#sl-safe) * ??? -### SL.1: Use libraries wherever possible +### SL.1: Use libraries wherever possible ##### Reason @@ -19780,7 +19780,7 @@ Don't replicate the work of others. Benefit from other people's work when they make improvements. Help other people when you make improvements. -### SL.2: Prefer the standard library to other libraries +### SL.2: Prefer the standard library to other libraries ##### Reason @@ -19833,18 +19833,18 @@ Summary of more specific rules: * [SL.4: Use the standard library in a type-safe manner](#sl-safe) -## SL.con: Containers +## SL.con: Containers ??? Container rule summary: -* [SL.con.1: Prefer using STL `array` or `vector` instead of a C array](#Rsl-arrays) -* [SL.con.2: Prefer using STL `vector` by default unless you have a reason to use a different container](#Rsl-vector) -* [SL.con.3: Avoid bounds errors](#Rsl-bounds) -* [SL.con.4: don't use `memset` or `memcpy` for arguments that are not trivially-copyable](#Rsl-copy) +* [SL.con.1: Prefer using STL `array` or `vector` instead of a C array](#rsl-arrays) +* [SL.con.2: Prefer using STL `vector` by default unless you have a reason to use a different container](#rsl-vector) +* [SL.con.3: Avoid bounds errors](#rsl-bounds) +* [SL.con.4: don't use `memset` or `memcpy` for arguments that are not trivially-copyable](#rsl-copy) -### SL.con.1: Prefer using STL `array` or `vector` instead of a C array +### SL.con.1: Prefer using STL `array` or `vector` instead of a C array ##### Reason @@ -19881,7 +19881,7 @@ People working with code for which that difference matters are quite capable of * Flag declaration of a C array inside a function or class that also declares an STL container (to avoid excessive noisy warnings on legacy non-STL code). To fix: At least change the C array to a `std::array`. -### SL.con.2: Prefer using STL `vector` by default unless you have a reason to use a different container +### SL.con.2: Prefer using STL `vector` by default unless you have a reason to use a different container ##### Reason @@ -19915,13 +19915,13 @@ To initialize a vector with a list of elements, use `{}`-initialization. vector v1(20); // v1 has 20 elements with the value 0 (vector{}) vector v2 {20}; // v2 has 1 element with the value 20 -[Prefer the {}-initializer syntax](#Res-list). +[Prefer the {}-initializer syntax](#res-list). ##### Enforcement * Flag a `vector` whose size never changes after construction (such as because it's `const` or because no non-`const` functions are called on it). To fix: Use an `array` instead. -### SL.con.3: Avoid bounds errors +### SL.con.3: Avoid bounds errors ##### Reason @@ -19992,10 +19992,10 @@ If code is using an unmodified standard library, then there are still workaround * Issue a diagnostic for any call to a standard-library function that is not bounds-checked. ??? insert link to a list of banned functions -This rule is part of the [bounds profile](#SS-bounds). +This rule is part of the [bounds profile](#ss-bounds). -### SL.con.4: don't use `memset` or `memcpy` for arguments that are not trivially-copyable +### SL.con.4: don't use `memset` or `memcpy` for arguments that are not trivially-copyable ##### Reason @@ -20044,37 +20044,37 @@ Instead, define proper default initialization, copy, and comparison functions -## SL.str: String +## SL.str: String Text manipulation is a huge topic. `std::string` doesn't cover all of it. This section primarily tries to clarify `std::string`'s relation to `char*`, `zstring`, `string_view`, and `gsl::span`. The important issue of non-ASCII character sets and encodings (e.g., `wchar_t`, Unicode, and UTF-8) will be covered elsewhere. -**See also**: [regular expressions](#SS-regex) +**See also**: [regular expressions](#ss-regex) Here, we use "sequence of characters" or "string" to refer to a sequence of characters meant to be read as text (somehow, eventually). We don't consider ??? String summary: -* [SL.str.1: Use `std::string` to own character sequences](#Rstr-string) -* [SL.str.2: Use `std::string_view` or `gsl::span` to refer to character sequences](#Rstr-view) -* [SL.str.3: Use `zstring` or `czstring` to refer to a C-style, zero-terminated, sequence of characters](#Rstr-zstring) -* [SL.str.4: Use `char*` to refer to a single character](#Rstr-char*) -* [SL.str.5: Use `std::byte` to refer to byte values that do not necessarily represent characters](#Rstr-byte) +* [SL.str.1: Use `std::string` to own character sequences](#rstr-string) +* [SL.str.2: Use `std::string_view` or `gsl::span` to refer to character sequences](#rstr-view) +* [SL.str.3: Use `zstring` or `czstring` to refer to a C-style, zero-terminated, sequence of characters](#rstr-zstring) +* [SL.str.4: Use `char*` to refer to a single character](#rstr-charp) +* [SL.str.5: Use `std::byte` to refer to byte values that do not necessarily represent characters](#rstr-byte) -* [SL.str.10: Use `std::string` when you need to perform locale-sensitive string operations](#Rstr-locale) -* [SL.str.11: Use `gsl::span` rather than `std::string_view` when you need to mutate a string](#Rstr-span) -* [SL.str.12: Use the `s` suffix for string literals meant to be standard-library `string`s](#Rstr-s) +* [SL.str.10: Use `std::string` when you need to perform locale-sensitive string operations](#rstr-locale) +* [SL.str.11: Use `gsl::span` rather than `std::string_view` when you need to mutate a string](#rstr-span) +* [SL.str.12: Use the `s` suffix for string literals meant to be standard-library `string`s](#rstr-s) **See also**: -* [F.24 span](#Rf-range) -* [F.25 zstring](#Rf-zstring) +* [F.24 span](#rf-range) +* [F.25 zstring](#rf-zstring) -### SL.str.1: Use `std::string` to own character sequences +### SL.str.1: Use `std::string` to own character sequences ##### Reason @@ -20127,13 +20127,13 @@ Will this code pass a security review? ##### Note Do not assume that `string` is slower than lower-level techniques without measurement and remember that not all code is performance critical. -[Don't optimize prematurely](#Rper-Knuth) +[Don't optimize prematurely](#rper-knuth) ##### Enforcement ??? -### SL.str.2: Use `std::string_view` or `gsl::span` to refer to character sequences +### SL.str.2: Use `std::string_view` or `gsl::span` to refer to character sequences ##### Reason @@ -20160,7 +20160,7 @@ those sequences are allocated and stored. ??? -### SL.str.3: Use `zstring` or `czstring` to refer to a C-style, zero-terminated, sequence of characters +### SL.str.3: Use `zstring` or `czstring` to refer to a C-style, zero-terminated, sequence of characters ##### Reason @@ -20200,7 +20200,7 @@ This is one of the major sources of bugs in C and C++ programs, so it is worthwh * Flag uses of `delete` on a `char*` * Flag uses of `free()` on a `char*` -### SL.str.4: Use `char*` to refer to a single character +### SL.str.4: Use `char*` to refer to a single character ##### Reason @@ -20224,13 +20224,13 @@ The array `arr` is not a C-style string because it is not zero-terminated. ##### Alternative -See [`zstring`](#Rstr-zstring), [`string`](#Rstr-string), and [`string_view`](#Rstr-view). +See [`zstring`](#rstr-zstring), [`string`](#rstr-string), and [`string_view`](#rstr-view). ##### Enforcement * Flag uses of `[]` on a `char*` -### SL.str.5: Use `std::byte` to refer to byte values that do not necessarily represent characters +### SL.str.5: Use `std::byte` to refer to byte values that do not necessarily represent characters ##### Reason @@ -20250,11 +20250,11 @@ C++17 ??? -### SL.str.10: Use `std::string` when you need to perform locale-sensitive string operations +### SL.str.10: Use `std::string` when you need to perform locale-sensitive string operations ##### Reason -`std::string` supports standard-library [`locale` facilities](#Rstr-locale) +`std::string` supports standard-library [`locale` facilities](#rstr-locale) ##### Example @@ -20268,7 +20268,7 @@ C++17 ??? -### SL.str.11: Use `gsl::span` rather than `std::string_view` when you need to mutate a string +### SL.str.11: Use `gsl::span` rather than `std::string_view` when you need to mutate a string ##### Reason @@ -20286,7 +20286,7 @@ C++17 The compiler will flag attempts to write to a `string_view`. -### SL.str.12: Use the `s` suffix for string literals meant to be standard-library `string`s +### SL.str.12: Use the `s` suffix for string literals meant to be standard-library `string`s ##### Reason @@ -20306,7 +20306,7 @@ Direct expression of an idea minimizes mistakes. ??? -## SL.io: Iostream +## SL.io: Iostream `iostream`s is a type safe, extensible, formatted and unformatted I/O library for streaming I/O. It supports multiple (and user extensible) buffering strategies and multiple locales. @@ -20315,14 +20315,14 @@ and user-defined extensions, such as streaming across networks (asio: not yet st Iostream rule summary: -* [SL.io.1: Use character-level input only when you have to](#Rio-low) -* [SL.io.2: When reading, always consider ill-formed input](#Rio-validate) -* [SL.io.3: Prefer iostreams for I/O](#Rio-streams) -* [SL.io.10: Unless you use `printf`-family functions call `ios_base::sync_with_stdio(false)`](#Rio-sync) -* [SL.io.50: Avoid `endl`](#Rio-endl) +* [SL.io.1: Use character-level input only when you have to](#rio-low) +* [SL.io.2: When reading, always consider ill-formed input](#rio-validate) +* [SL.io.3: Prefer iostreams for I/O](#rio-streams) +* [SL.io.10: Unless you use `printf`-family functions call `ios_base::sync_with_stdio(false)`](#rio-sync) +* [SL.io.50: Avoid `endl`](#rio-endl) * [???](#???) -### SL.io.1: Use character-level input only when you have to +### SL.io.1: Use character-level input only when you have to ##### Reason @@ -20353,7 +20353,7 @@ and the `reserve(128)` is probably not worthwhile. ??? -### SL.io.2: When reading, always consider ill-formed input +### SL.io.2: When reading, always consider ill-formed input ##### Reason @@ -20368,7 +20368,7 @@ If input isn't validated, every function must be written to cope with bad data ( ??? -### SL.io.3: Prefer `iostream`s for I/O +### SL.io.3: Prefer `iostream`s for I/O ##### Reason @@ -20409,7 +20409,7 @@ If present in your C library, `gets_s()`, `scanf_s()`, and `printf_s()` might be Optionally flag `` and ``. -### SL.io.10: Unless you use `printf`-family functions call `ios_base::sync_with_stdio(false)` +### SL.io.10: Unless you use `printf`-family functions call `ios_base::sync_with_stdio(false)` ##### Reason @@ -20428,7 +20428,7 @@ Synchronizing `iostreams` with `printf-style` I/O can be costly. ??? -### SL.io.50: Avoid `endl` +### SL.io.50: Avoid `endl` ##### Reason @@ -20459,28 +20459,28 @@ Windows). So for a string stream, `s << endl` just inserts a *single* character, Apart from the (occasionally important) issue of performance, the choice between `'\n'` and `endl` is almost completely aesthetic. -## SL.regex: Regex +## SL.regex: Regex `` is the standard C++ regular expression library. It supports a variety of regular expression pattern conventions. -## SL.chrono: Time +## SL.chrono: Time `` (defined in namespace `std::chrono`) provides the notions of `time_point` and `duration` together with functions for outputting time in various units. It provides clocks for registering `time_points`. -## SL.C: The C Standard Library +## SL.C: The C Standard Library ??? C Standard Library rule summary: -* [SL.C.1: Don't use setjmp/longjmp](#Rclib-jmp) +* [SL.C.1: Don't use setjmp/longjmp](#rclib-jmp) * [???](#???) * [???](#???) -### SL.C.1: Don't use setjmp/longjmp +### SL.C.1: Don't use setjmp/longjmp ##### Reason @@ -20492,15 +20492,15 @@ Flag all occurrences of `longjmp`and `setjmp` -# A: Architectural ideas +# A: Architectural ideas This section contains ideas about higher-level architectural ideas and libraries. Architectural rule summary: -* [A.1: Separate stable code from less stable code](#Ra-stable) -* [A.2: Express potentially reusable parts as a library](#Ra-lib) -* [A.4: There should be no cycles among libraries](#Ra-dag) +* [A.1: Separate stable code from less stable code](#ra-stable) +* [A.2: Express potentially reusable parts as a library](#ra-lib) +* [A.4: There should be no cycles among libraries](#ra-dag) * [???](#???) * [???](#???) * [???](#???) @@ -20508,11 +20508,11 @@ Architectural rule summary: * [???](#???) * [???](#???) -### A.1: Separate stable code from less stable code +### A.1: Separate stable code from less stable code Isolating less stable code facilitates its unit testing, interface improvement, refactoring, and eventual deprecation. -### A.2: Express potentially reusable parts as a library +### A.2: Express potentially reusable parts as a library ##### Reason @@ -20523,7 +20523,7 @@ A library could be a set of headers (a "header-only library") or a set of header You can statically or dynamically link a library into a program, or you can `#include` a header-only library. -### A.4: There should be no cycles among libraries +### A.4: There should be no cycles among libraries ##### Reason @@ -20540,7 +20540,7 @@ For example: However, a library should not depend on another that depends on it. -# NR: Non-Rules and myths +# NR: Non-Rules and myths This section contains rules and guidelines that are popular somewhere, but that we deliberately don't recommend. We know perfectly well that there have been times and places where these rules made sense, and we have used them ourselves at times. @@ -20556,16 +20556,16 @@ The positive arguments for alternatives to these non-rules are listed in the rul Non-rule summary: -* [NR.1: Don't insist that all declarations should be at the top of a function](#Rnr-top) -* [NR.2: Don't insist on having only a single `return`-statement in a function](#Rnr-single-return) -* [NR.3: Don't avoid exceptions](#Rnr-no-exceptions) -* [NR.4: Don't insist on placing each class definition in its own source file](#Rnr-lots-of-files) -* [NR.5: Don't use two-phase initialization](#Rnr-two-phase-init) -* [NR.6: Don't place all cleanup actions at the end of a function and `goto exit`](#Rnr-goto-exit) -* [NR.7: Don't make data members `protected`](#Rnr-protected-data) +* [NR.1: Don't insist that all declarations should be at the top of a function](#rnr-top) +* [NR.2: Don't insist on having only a single `return`-statement in a function](#rnr-single-return) +* [NR.3: Don't avoid exceptions](#rnr-no-exceptions) +* [NR.4: Don't insist on placing each class definition in its own source file](#rnr-lots-of-files) +* [NR.5: Don't use two-phase initialization](#rnr-two-phase-init) +* [NR.6: Don't place all cleanup actions at the end of a function and `goto exit`](#rnr-goto-exit) +* [NR.7: Don't make data members `protected`](#rnr-protected-data) * ??? -### NR.1: Don't insist that all declarations should be at the top of a function +### NR.1: Don't insist that all declarations should be at the top of a function ##### Reason @@ -20600,10 +20600,10 @@ Unfortunately, compilers cannot catch all such errors and unfortunately, the bug ##### Alternative -* [Always initialize an object](#Res-always) -* [ES.21: Don't introduce a variable (or constant) before you need to use it](#Res-introduce) +* [Always initialize an object](#res-always) +* [ES.21: Don't introduce a variable (or constant) before you need to use it](#res-introduce) -### NR.2: Don't insist on having only a single `return`-statement in a function +### NR.2: Don't insist on having only a single `return`-statement in a function ##### Reason @@ -20666,14 +20666,14 @@ If we applied the rule, we'd get something like } Note that we (deliberately) violated the rule against uninitialized variables because this style commonly leads to that. -Also, this style is a temptation to use the [goto exit](#Rnr-goto-exit) non-rule. +Also, this style is a temptation to use the [goto exit](#rnr-goto-exit) non-rule. ##### Alternative * Keep functions short and simple * Feel free to use multiple `return` statements (and to throw exceptions). -### NR.3: Don't avoid exceptions +### NR.3: Don't avoid exceptions ##### Reason @@ -20744,10 +20744,10 @@ Remember ##### Alternative -* [RAII](#Re-raii) +* [RAII](#re-raii) * Contracts/assertions: Use GSL's `Expects` and `Ensures` (until we get language support for contracts) -### NR.4: Don't insist on placing each class definition in its own source file +### NR.4: Don't insist on placing each class definition in its own source file ##### Reason @@ -20762,7 +20762,7 @@ Individual classes are rarely a good logical unit of maintenance and distributio * Use namespaces containing logically cohesive sets of classes and functions. -### NR.5: Don't use two-phase initialization +### NR.5: Don't use two-phase initialization ##### Reason @@ -20874,7 +20874,7 @@ Sometimes also called two-stage construction. * Always establish a class invariant in a constructor. * Don't define an object before it is needed. -### NR.6: Don't place all cleanup actions at the end of a function and `goto exit` +### NR.6: Don't place all cleanup actions at the end of a function and `goto exit` ##### Reason @@ -20899,10 +20899,10 @@ and spot the bug. ##### Alternative -* Use exceptions and [RAII](#Re-raii) -* for non-RAII resources, use [`finally`](#Re-finally). +* Use exceptions and [RAII](#re-raii) +* for non-RAII resources, use [`finally`](#re-finally). -### NR.7: Don't make data members `protected` +### NR.7: Don't make data members `protected` ##### Reason @@ -20916,10 +20916,10 @@ and spot the bug. ##### Alternative -* [Avoid `protected` data](#Rh-protected) +* [Avoid `protected` data](#rh-protected) -# RF: References +# RF: References Many coding standards, rules, and guidelines have been written for C++, and especially for specialized uses of C++. Many @@ -20947,15 +20947,15 @@ We expect different organizations to provide additions, typically with more rest Reference sections: -* [RF.rules: Coding rules](#SS-rules) -* [RF.books: Books with coding guidelines](#SS-books) -* [RF.C++: C++ Programming (C++11/C++14/C++17)](#SS-Cplusplus) -* [RF.web: Websites](#SS-web) -* [RS.video: Videos about "modern C++"](#SS-vid) -* [RF.man: Manuals](#SS-man) -* [RF.core: Core Guidelines materials](#SS-core) +* [RF.rules: Coding rules](#ss-rules) +* [RF.books: Books with coding guidelines](#ss-books) +* [RF.C++: C++ Programming (C++11/C++14/C++17)](#ss-cplusplus) +* [RF.web: Websites](#ss-web) +* [RS.video: Videos about "modern C++"](#ss-vid) +* [RF.man: Manuals](#ss-man) +* [RF.core: Core Guidelines materials](#ss-core) -## RF.rules: Coding rules +## RF.rules: Coding rules * [AUTOSAR Guidelines for the use of the C++14 language in critical and safety-related systems v22.11](https://www.autosar.org/fileadmin/standards/R22-11/AP/AUTOSAR_RS_CPP14Guidelines.pdf) (obsolete, replaced by [MISRA C++:2023](https://misra.org.uk/product/misra-cpp2023/)) * [Boost Library Requirements and Guidelines](http://www.boost.org/development/requirements.html). @@ -20993,7 +20993,7 @@ Reference sections: Somewhat brief, based on C++14, and (not unreasonably) adjusted to its domain. * ??? -## RF.books: Books with coding guidelines +## RF.books: Books with coding guidelines * [Meyers96](#Meyers96) Scott Meyers: *More Effective C++*. Addison-Wesley 1996. * [Meyers97](#Meyers97) Scott Meyers: *Effective C++, Second Edition*. Addison-Wesley 1997. @@ -21014,7 +21014,7 @@ Reference sections: Mostly low-level naming and layout rules. Primarily a teaching tool. -## RF.C++: C++ Programming (C++11/C++14) +## RF.C++: C++ Programming (C++11/C++14) * [TC++PL4](http://www.stroustrup.com/4th.html): A thorough description of the C++ language and standard libraries for experienced programmers. @@ -21023,7 +21023,7 @@ An overview of the C++ language and standard libraries for experienced programme * [Programming: Principles and Practice using C++](http://www.stroustrup.com/programming.html): A textbook for beginners and relative novices. -## RF.web: Websites +## RF.web: Websites * [isocpp.org](https://isocpp.org) * [Bjarne Stroustrup's home pages](http://www.stroustrup.com) @@ -21034,7 +21034,7 @@ A textbook for beginners and relative novices. * Sutter's Mill? * ??? -## RS.video: Videos about "modern C++" +## RS.video: Videos about "modern C++" * Bjarne Stroustrup: [C++11 Style](http://channel9.msdn.com/Events/GoingNative/GoingNative-2012/Keynote-Bjarne-Stroustrup-Cpp11-Style). 2012. * Bjarne Stroustrup: [The Essence of C++: With Examples in C++84, C++98, C++11, and C++14](http://channel9.msdn.com/Events/GoingNative/2013/Opening-Keynote-Bjarne-Stroustrup). 2013 @@ -21049,7 +21049,7 @@ A textbook for beginners and relative novices. * ??? Meting C++ * ??? more ??? -## RF.man: Manuals +## RF.man: Manuals * ISO C++ Standard C++11. * ISO C++ Standard C++14. @@ -21059,7 +21059,7 @@ A textbook for beginners and relative novices. * [WG21 Ranges report](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/n4569.pdf). Draft. -## RF.core: Core Guidelines materials +## RF.core: Core Guidelines materials This section contains materials that have been useful for presenting the core guidelines and the ideas behind them: @@ -21078,7 +21078,7 @@ Note that slides for CppCon presentations are available (links with the posted v Contributions to this list would be most welcome. -## Acknowledgements +## Acknowledgements Thanks to the many people who contributed rules, suggestions, supporting information, references, etc.: @@ -21092,13 +21092,13 @@ Thanks to the many people who contributed rules, suggestions, supporting informa and see the contributor list on the github. -# Pro: Profiles +# Pro: Profiles Ideally, we would follow all of the guidelines. That would give the cleanest, most regular, least error-prone, and often the fastest code. Unfortunately, that is usually impossible because we have to fit our code into large code bases and use existing libraries. Often, such code has been written over decades and does not follow these guidelines. -We must aim for [gradual adoption](#S-modernizing). +We must aim for [gradual adoption](#s-modernizing). Whatever strategy for gradual adoption we adopt, we need to be able to apply sets of related guidelines to address some set of problems first and leave the rest until later. @@ -21122,9 +21122,9 @@ A profile might also introduce additional library types to ease conformance and Profiles summary: -* [Pro.type: Type safety](#SS-type) -* [Pro.bounds: Bounds safety](#SS-bounds) -* [Pro.lifetime: Lifetime safety](#SS-lifetime) +* [Pro.type: Type safety](#ss-type) +* [Pro.bounds: Bounds safety](#ss-bounds) +* [Pro.lifetime: Lifetime safety](#ss-lifetime) In the future, we expect to define many more profiles and add more checks to existing profiles. Candidates include: @@ -21147,7 +21147,7 @@ To suppress enforcement of a profile check, place a `suppress` annotation on a l Now `raw_find()` can scramble memory to its heart's content. Obviously, suppression should be very rare. -## Pro.safety: Type-safety profile +## Pro.safety: Type-safety profile This profile makes it easier to construct code that uses types correctly and avoids inadvertent type punning. It does so by focusing on removing the primary sources of type violations, including unsafe uses of casts and unions. @@ -21155,63 +21155,63 @@ It does so by focusing on removing the primary sources of type violations, inclu For the purposes of this section, type-safety is defined to be the property that a variable is not used in a way that doesn't obey the rules for the type of its definition. Memory accessed as a type `T` should not be valid memory that actually contains an object of an unrelated type `U`. -Note that the safety is intended to be complete when combined also with [Bounds safety](#SS-bounds) and [Lifetime safety](#SS-lifetime). +Note that the safety is intended to be complete when combined also with [Bounds safety](#ss-bounds) and [Lifetime safety](#ss-lifetime). An implementation of this profile shall recognize the following patterns in source code as non-conforming and issue a diagnostic. Type safety profile summary: -* Type.1: [Avoid casts](#Res-casts): - - 1. Don't use `reinterpret_cast`; A strict version of [Avoid casts](#Res-casts) and [prefer named casts](#Res-casts-named). - 2. Don't use `static_cast` for arithmetic types; A strict version of [Avoid casts](#Res-casts) and [prefer named casts](#Res-casts-named). - 3. Don't cast between pointer types where the source type and the target type are the same; A strict version of [Avoid casts](#Res-casts). - 4. Don't cast between pointer types when the conversion could be implicit; A strict version of [Avoid casts](#Res-casts). -* Type.2: Don't use `static_cast` to downcast: -[Use `dynamic_cast` instead](#Rh-dynamic_cast). -* Type.3: Don't use `const_cast` to cast away `const` (i.e., at all): -[Don't cast away const](#Res-casts-const). -* Type.4: Don't use C-style `(T)expression` or functional `T(expression)` casts: -Prefer [construction](#Res-construct) or [named casts](#Res-casts-named) or `T{expression}`. -* Type.5: Don't use a variable before it has been initialized: -[always initialize](#Res-always). -* Type.6: Always initialize a data member: -[always initialize](#Res-always), -possibly using [default constructors](#Rc-default0) or -[default member initializers](#Rc-in-class-initializer). -* Type.7: Avoid naked union: -[Use `variant` instead](#Ru-naked). -* Type.8: Avoid varargs: -[Don't use `va_arg` arguments](#F-varargs). +* Type.1: [Avoid casts](#res-casts): + + 1. Don't use `reinterpret_cast`; A strict version of [Avoid casts](#res-casts) and [prefer named casts](#res-casts-named). + 2. Don't use `static_cast` for arithmetic types; A strict version of [Avoid casts](#res-casts) and [prefer named casts](#res-casts-named). + 3. Don't cast between pointer types where the source type and the target type are the same; A strict version of [Avoid casts](#res-casts). + 4. Don't cast between pointer types when the conversion could be implicit; A strict version of [Avoid casts](#res-casts). +* Type.2: Don't use `static_cast` to downcast: +[Use `dynamic_cast` instead](#rh-dynamic_cast). +* Type.3: Don't use `const_cast` to cast away `const` (i.e., at all): +[Don't cast away const](#res-casts-const). +* Type.4: Don't use C-style `(T)expression` or functional `T(expression)` casts: +Prefer [construction](#res-construct) or [named casts](#res-casts-named) or `T{expression}`. +* Type.5: Don't use a variable before it has been initialized: +[always initialize](#res-always). +* Type.6: Always initialize a data member: +[always initialize](#res-always), +possibly using [default constructors](#rc-default0) or +[default member initializers](#rc-in-class-initializer). +* Type.7: Avoid naked union: +[Use `variant` instead](#ru-naked). +* Type.8: Avoid varargs: +[Don't use `va_arg` arguments](#f-varargs). ##### Impact With the type-safety profile you can trust that every operation is applied to a valid object. An exception can be thrown to indicate errors that cannot be detected statically (at compile time). -Note that this type-safety can be complete only if we also have [Bounds safety](#SS-bounds) and [Lifetime safety](#SS-lifetime). +Note that this type-safety can be complete only if we also have [Bounds safety](#ss-bounds) and [Lifetime safety](#ss-lifetime). Without those guarantees, a region of memory could be accessed independent of which object, objects, or parts of objects are stored in it. -## Pro.bounds: Bounds safety profile +## Pro.bounds: Bounds safety profile This profile makes it easier to construct code that operates within the bounds of allocated blocks of memory. It does so by focusing on removing the primary sources of bounds violations: pointer arithmetic and array indexing. One of the core features of this profile is to restrict pointers to only refer to single objects, not arrays. We define bounds-safety to be the property that a program does not use an object to access memory outside of the range that was allocated for it. -Bounds safety is intended to be complete only when combined with [Type safety](#SS-type) and [Lifetime safety](#SS-lifetime), +Bounds safety is intended to be complete only when combined with [Type safety](#ss-type) and [Lifetime safety](#ss-lifetime), which cover other unsafe operations that allow bounds violations. Bounds safety profile summary: -* Bounds.1: Don't use pointer arithmetic. Use `span` instead: -[Pass pointers to single objects (only)](#Ri-array) and [Keep pointer arithmetic simple](#Res-ptr). -* Bounds.2: Only index into arrays using constant expressions: -[Pass pointers to single objects (only)](#Ri-array) and [Keep pointer arithmetic simple](#Res-ptr). -* Bounds.3: No array-to-pointer decay: -[Pass pointers to single objects (only)](#Ri-array) and [Keep pointer arithmetic simple](#Res-ptr). -* Bounds.4: Don't use standard-library functions and types that are not bounds-checked: -[Use the standard library in a type-safe manner](#Rsl-bounds). +* Bounds.1: Don't use pointer arithmetic. Use `span` instead: +[Pass pointers to single objects (only)](#ri-array) and [Keep pointer arithmetic simple](#res-ptr). +* Bounds.2: Only index into arrays using constant expressions: +[Pass pointers to single objects (only)](#ri-array) and [Keep pointer arithmetic simple](#res-ptr). +* Bounds.3: No array-to-pointer decay: +[Pass pointers to single objects (only)](#ri-array) and [Keep pointer arithmetic simple](#res-ptr). +* Bounds.4: Don't use standard-library functions and types that are not bounds-checked: +[Use the standard library in a type-safe manner](#rsl-bounds). ##### Impact @@ -21222,7 +21222,7 @@ Even if an out-of-bounds access is "just a read", it can lead to invariant viola and "mysterious values." -## Pro.lifetime: Lifetime safety profile +## Pro.lifetime: Lifetime safety profile Accessing through a pointer that doesn't point to anything is a major source of errors, and very hard to avoid in many traditional C or C++ styles of programming. @@ -21232,8 +21232,8 @@ For example, a pointer might be uninitialized, the `nullptr`, point beyond the r Lifetime safety profile summary: -* Lifetime.1: Don't dereference a possibly invalid pointer: -[detect or avoid](#Res-deref). +* Lifetime.1: Don't dereference a possibly invalid pointer: +[detect or avoid](#res-deref). ##### Impact @@ -21268,23 +21268,23 @@ For each GSL type below we state an invariant for that type. That invariant hold Summary of GSL components: -* [GSL.view: Views](#SS-views) -* [GSL.owner: Ownership pointers](#SS-ownership) -* [GSL.assert: Assertions](#SS-assertions) -* [GSL.util: Utilities](#SS-utilities) -* [GSL.concept: Concepts](#SS-gsl-concepts) +* [GSL.view: Views](#ss-views) +* [GSL.owner: Ownership pointers](#ss-ownership) +* [GSL.assert: Assertions](#ss-assertions) +* [GSL.util: Utilities](#ss-utilities) +* [GSL.concept: Concepts](#ss-gsl-concepts) We plan for a "ISO C++ standard style" semi-formal specification of the GSL. We rely on the ISO C++ Standard Library and hope for parts of the GSL to be absorbed into the standard library. -## GSL.view: Views +## GSL.view: Views These types allow the user to distinguish between owning and non-owning pointers and between pointers to a single object and pointers to the first element of a sequence. These "views" are never owners. -References are never owners (see [R.4](#Rr-ref)). Note: References have many opportunities to outlive the objects they refer to (returning a local variable by reference, holding a reference to an element of a vector and doing `push_back`, binding to `std::max(x, y + 1)`, etc). The Lifetime safety profile aims to address those things, but even so `owner` does not make sense and is discouraged. +References are never owners (see [R.4](#rr-ref)). Note: References have many opportunities to outlive the objects they refer to (returning a local variable by reference, holding a reference to an element of a vector and doing `push_back`, binding to `std::max(x, y + 1)`, etc). The Lifetime safety profile aims to address those things, but even so `owner` does not make sense and is discouraged. The names are mostly ISO standard-library style (lower case and underscore): @@ -21331,7 +21331,7 @@ A sequence of characters that is not assumed to be zero-terminated should be a ` Use `not_null` for C-style strings that cannot be `nullptr`. ??? Do we need a name for `not_null`? or is its ugliness a feature? -## GSL.owner: Ownership pointers +## GSL.owner: Ownership pointers * `unique_ptr` // unique ownership: `std::unique_ptr` * `shared_ptr` // shared ownership: `std::shared_ptr` (a counted pointer) @@ -21339,7 +21339,7 @@ Use `not_null` for C-style strings that cannot be `nullptr`. ??? Do we * `dyn_array` // A container, non-growing dynamically allocated array. The number of elements is determined at construction and fixed thereafter. The elements are mutable unless `T` is a `const` type. Basically a `span` that allocates and owns its elements. -## GSL.assert: Assertions +## GSL.assert: Assertions * `Expects` // precondition assertion. Currently placed in function bodies. Later, should be moved to declarations. // `Expects(p)` terminates the program unless `p == true` @@ -21351,7 +21351,7 @@ pending standard committee decisions on contracts and assertion syntax. See [the contract proposal](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0380r1.pdf); using the attribute syntax, for example, `Expects(p)` will become `[[expects: p]]`. -## GSL.util: Utilities +## GSL.util: Utilities * `finally` // `finally(f)` makes a `final_action{f}` with a destructor that invokes `f` * `narrow_cast` // `narrow_cast(x)` is `static_cast(x)` @@ -21361,7 +21361,7 @@ for example, `Expects(p)` will become `[[expects: p]]`. * `joining_thread` // a RAII style version of `std::thread` that joins. * `index` // a type to use for all container and array indexing (currently an alias for `ptrdiff_t`) -## GSL.concept: Concepts +## GSL.concept: Concepts These concepts (type predicates) are borrowed from Andrew Sutton's Origin library, @@ -21388,13 +21388,13 @@ Many of them are very similar to what became part of the ISO C++ standard in C++ * `Relation` // in C++20, `std::relation` * ... -### GSL.ptr: Smart pointer concepts +### GSL.ptr: Smart pointer concepts * `Pointer` // A type with `*`, `->`, `==`, and default construction (default construction is assumed to set the singular "null" value) * `Unique_pointer` // A type that matches `Pointer`, is movable, and is not copyable * `Shared_pointer` // A type that matches `Pointer`, and is copyable -# NL: Naming and layout suggestions +# NL: Naming and layout suggestions Consistent naming and layout are helpful. If for no other reason because it minimizes "my style is better than your style" arguments. @@ -21405,26 +21405,26 @@ IDEs and tools can help (as well as hinder). Naming and layout rules: -* [NL.1: Don't say in comments what can be clearly stated in code](#Rl-comments) -* [NL.2: State intent in comments](#Rl-comments-intent) -* [NL.3: Keep comments crisp](#Rl-comments-crisp) -* [NL.4: Maintain a consistent indentation style](#Rl-indent) -* [NL.5: Avoid encoding type information in names](#Rl-name-type) -* [NL.7: Make the length of a name roughly proportional to the length of its scope](#Rl-name-length) -* [NL.8: Use a consistent naming style](#Rl-name) -* [NL.9: Use `ALL_CAPS` for macro names only](#Rl-all-caps) -* [NL.10: Prefer `underscore_style` names](#Rl-camel) -* [NL.11: Make literals readable](#Rl-literals) -* [NL.15: Use spaces sparingly](#Rl-space) -* [NL.16: Use a conventional class member declaration order](#Rl-order) -* [NL.17: Use K&R-derived layout](#Rl-knr) -* [NL.18: Use C++-style declarator layout](#Rl-ptr) -* [NL.19: Avoid names that are easily misread](#Rl-misread) -* [NL.20: Don't place two statements on the same line](#Rl-stmt) -* [NL.21: Declare one name (only) per declaration](#Rl-dcl) -* [NL.25: Don't use `void` as an argument type](#Rl-void) -* [NL.26: Use conventional `const` notation](#Rl-const) -* [NL.27: Use a `.cpp` suffix for code files and `.h` for interface files](#Rl-file-suffix) +* [NL.1: Don't say in comments what can be clearly stated in code](#rl-comments) +* [NL.2: State intent in comments](#rl-comments-intent) +* [NL.3: Keep comments crisp](#rl-comments-crisp) +* [NL.4: Maintain a consistent indentation style](#rl-indent) +* [NL.5: Avoid encoding type information in names](#rl-name-type) +* [NL.7: Make the length of a name roughly proportional to the length of its scope](#rl-name-length) +* [NL.8: Use a consistent naming style](#rl-name) +* [NL.9: Use `ALL_CAPS` for macro names only](#rl-all-caps) +* [NL.10: Prefer `underscore_style` names](#rl-camel) +* [NL.11: Make literals readable](#rl-literals) +* [NL.15: Use spaces sparingly](#rl-space) +* [NL.16: Use a conventional class member declaration order](#rl-order) +* [NL.17: Use K&R-derived layout](#rl-knr) +* [NL.18: Use C++-style declarator layout](#rl-ptr) +* [NL.19: Avoid names that are easily misread](#rl-misread) +* [NL.20: Don't place two statements on the same line](#rl-stmt) +* [NL.21: Declare one name (only) per declaration](#rl-dcl) +* [NL.25: Don't use `void` as an argument type](#rl-void) +* [NL.26: Use conventional `const` notation](#rl-const) +* [NL.27: Use a `.cpp` suffix for code files and `.h` for interface files](#rl-file-suffix) Most of these rules are aesthetic and programmers hold strong opinions. IDEs also tend to have defaults and a range of alternatives. @@ -21439,7 +21439,7 @@ More specific and detailed rules are easier to enforce. These rules bear a strong resemblance to the recommendations in the [PPP Style Guide](http://www.stroustrup.com/Programming/PPP-style.pdf) written in support of Stroustrup's [Programming: Principles and Practice using C++](http://www.stroustrup.com/programming.html). -### NL.1: Don't say in comments what can be clearly stated in code +### NL.1: Don't say in comments what can be clearly stated in code ##### Reason @@ -21455,7 +21455,7 @@ Comments are not updated as consistently as code. Build an AI program that interprets colloquial English text and see if what is said could be better expressed in C++. -### NL.2: State intent in comments +### NL.2: State intent in comments ##### Reason @@ -21474,7 +21474,7 @@ Code says what is done, not what is supposed to be done. Often intent can be sta If the comment and the code disagree, both are likely to be wrong. -### NL.3: Keep comments crisp +### NL.3: Keep comments crisp ##### Reason @@ -21491,7 +21491,7 @@ Aim for professionalism, not "cool." not possible. -### NL.4: Maintain a consistent indentation style +### NL.4: Maintain a consistent indentation style ##### Reason @@ -21517,7 +21517,7 @@ Always indenting the statement after `if (...)`, `for (...)`, and `while (...)` Use a tool. -### NL.5: Avoid encoding type information in names +### NL.5: Avoid encoding type information in names ##### Rationale @@ -21591,7 +21591,7 @@ For example, by capitalizing type names, but not the names of functions and vari This is not harmful and does not fall under this guideline because it does not encode type information. -### NL.7: Make the length of a name roughly proportional to the length of its scope +### NL.7: Make the length of a name roughly proportional to the length of its scope **Rationale**: The larger the scope the greater the chance of confusion and of an unintended name clash. @@ -21613,7 +21613,7 @@ The use of `p` for pointer and `x` for a floating-point variable is conventional ??? -### NL.8: Use a consistent naming style +### NL.8: Use a consistent naming style **Rationale**: Consistency in naming and naming style increases readability. @@ -21664,7 +21664,7 @@ Try to be consistent in your use of acronyms and lengths of identifiers: Would be possible except for the use of libraries with varying conventions. -### NL.9: Use `ALL_CAPS` for macro names only +### NL.9: Use `ALL_CAPS` for macro names only ##### Reason @@ -21680,7 +21680,7 @@ To avoid confusing macros with names that obey scope and type rules. ##### Note -In particular, this avoids confusing macros with non-macro symbolic constants (see also [Enum.5: Don't use `ALL_CAPS` for enumerators](#Renum-caps)) +In particular, this avoids confusing macros with non-macro symbolic constants (see also [Enum.5: Don't use `ALL_CAPS` for enumerators](#renum-caps)) enum bad { BAD, WORSE, HORRIBLE }; // BAD @@ -21689,7 +21689,7 @@ In particular, this avoids confusing macros with non-macro symbolic constants (s * Flag macros with lower-case letters * Flag `ALL_CAPS` non-macro names -### NL.10: Prefer `underscore_style` names +### NL.10: Prefer `underscore_style` names ##### Reason @@ -21698,10 +21698,10 @@ The use of underscores to separate parts of a name is the original C and C++ sty ##### Note This rule is a default to use only if you have a choice. -Often, you don't have a choice and must follow an established style for [consistency](#Rl-name). +Often, you don't have a choice and must follow an established style for [consistency](#rl-name). The need for consistency beats personal taste. -This is a recommendation for [when you have no constraints or better ideas](#S-naming). +This is a recommendation for [when you have no constraints or better ideas](#s-naming). This rule was added after many requests for guidance. ##### Example @@ -21717,7 +21717,7 @@ ISO Standard, but with upper case used for your own types and concepts: Impossible. -### NL.11: Make literals readable +### NL.11: Make literals readable ##### Reason @@ -21741,7 +21741,7 @@ Use literal suffixes where clarification is needed ##### Note -Literals should not be sprinkled all over the code as ["magic constants"](#Res-magic), +Literals should not be sprinkled all over the code as ["magic constants"](#res-magic), but it is still a good idea to make them readable where they are defined. It is easy to make a typo in a long string of integers. @@ -21749,7 +21749,7 @@ It is easy to make a typo in a long string of integers. Flag long digit sequences. The trouble is to define "long"; maybe 7. -### NL.15: Use spaces sparingly +### NL.15: Use spaces sparingly ##### Reason @@ -21777,14 +21777,14 @@ Too much space makes the text larger and distracts. Some IDEs have their own opinions and add distracting space. -This is a recommendation for [when you have no constraints or better ideas](#S-naming). +This is a recommendation for [when you have no constraints or better ideas](#s-naming). This rule was added after many requests for guidance. ##### Note We value well-placed whitespace as a significant help for readability. Just don't overdo it. -### NL.16: Use a conventional class member declaration order +### NL.16: Use a conventional class member declaration order ##### Reason @@ -21799,7 +21799,7 @@ When declaring a class use the following order Use the `public` before `protected` before `private` order. -This is a recommendation for [when you have no constraints or better ideas](#S-naming). +This is a recommendation for [when you have no constraints or better ideas](#s-naming). This rule was added after many requests for guidance. ##### Example @@ -21846,7 +21846,7 @@ However, using macros obscures what is being expressed anyway. Flag departures from the suggested order. There will be a lot of old code that doesn't follow this rule. -### NL.17: Use K&R-derived layout +### NL.17: Use K&R-derived layout ##### Reason @@ -21856,7 +21856,7 @@ This is the original C and C++ layout. It preserves vertical space well. It dist In the context of C++, this style is often called "Stroustrup". -This is a recommendation for [when you have no constraints or better ideas](#S-naming). +This is a recommendation for [when you have no constraints or better ideas](#s-naming). This rule was added after many requests for guidance. ##### Example @@ -21917,7 +21917,7 @@ Do not capitalize function names. If you want enforcement, use an IDE to reformat. -### NL.18: Use C++-style declarator layout +### NL.18: Use C++-style declarator layout ##### Reason @@ -21932,7 +21932,7 @@ The use in expressions argument doesn't hold for references. ##### Note -This is a recommendation for [when you have no constraints or better ideas](#S-naming). +This is a recommendation for [when you have no constraints or better ideas](#s-naming). This rule was added after many requests for guidance. ##### Enforcement @@ -21940,7 +21940,7 @@ This rule was added after many requests for guidance. Impossible in the face of history. -### NL.19: Avoid names that are easily misread +### NL.19: Avoid names that are easily misread ##### Reason @@ -21959,7 +21959,7 @@ We easily confuse similarly spelled and slightly misspelled words. ??? -### NL.20: Don't place two statements on the same line +### NL.20: Don't place two statements on the same line ##### Reason @@ -21975,7 +21975,7 @@ It is really easy to overlook a statement when there is more on a line. Easy. -### NL.21: Declare one name (only) per declaration +### NL.21: Declare one name (only) per declaration ##### Reason @@ -21984,10 +21984,10 @@ Minimizing confusion with the declarator syntax. ##### Note -For details, see [ES.10](#Res-name-one). +For details, see [ES.10](#res-name-one). -### NL.25: Don't use `void` as an argument type +### NL.25: Don't use `void` as an argument type ##### Reason @@ -22009,7 +22009,7 @@ You can make an argument for that abomination in C when function prototypes were would have caused major problems, but not in the 21st century and in C++. -### NL.26: Use conventional `const` notation +### NL.26: Use conventional `const` notation ##### Reason @@ -22031,14 +22031,14 @@ but they also confuse more people, especially novices relying on teaching materi As ever, remember that the aim of these naming and layout rules is consistency and that aesthetics vary immensely. -This is a recommendation for [when you have no constraints or better ideas](#S-naming). +This is a recommendation for [when you have no constraints or better ideas](#s-naming). This rule was added after many requests for guidance. ##### Enforcement Flag `const` used as a suffix for a type. -### NL.27: Use a `.cpp` suffix for code files and `.h` for interface files +### NL.27: Use a `.cpp` suffix for code files and `.h` for interface files ##### Reason @@ -22085,47 +22085,47 @@ Your IDE (if you use one) might have strong opinions about suffixes. * Flag non-conventional file names. * Check that `.h` and `.cpp` (and equivalents) follow the rules below. -# FAQ: Answers to frequently asked questions +# FAQ: Answers to frequently asked questions This section covers answers to frequently asked questions about these guidelines. -### FAQ.1: What do these guidelines aim to achieve? +### FAQ.1: What do these guidelines aim to achieve? -See the top of this page. This is an open-source project to maintain modern authoritative guidelines for writing C++ code using the current C++ Standard. The guidelines are designed to be modern, machine-enforceable wherever possible, and open to contributions and forking so that organizations can easily incorporate them into their own corporate coding guidelines. +See the top of this page. This is an open-source project to maintain modern authoritative guidelines for writing C++ code using the current C++ Standard. The guidelines are designed to be modern, machine-enforceable wherever possible, and open to contributions and forking so that organizations can easily incorporate them into their own corporate coding guidelines. -### FAQ.2: When and where was this work first announced? +### FAQ.2: When and where was this work first announced? It was announced by [Bjarne Stroustrup in his CppCon 2015 opening keynote, "Writing Good C++14"](https://isocpp.org/blog/2015/09/stroustrup-cppcon15-keynote). See also the [accompanying isocpp.org blog post](https://isocpp.org/blog/2015/09/bjarne-stroustrup-announces-cpp-core-guidelines), and for the rationale of the type and memory safety guidelines see [Herb Sutter's follow-up CppCon 2015 talk, "Writing Good C++14 ... By Default"](https://isocpp.org/blog/2015/09/sutter-cppcon15-day2plenary). -### FAQ.3: Who are the authors and maintainers of these guidelines? +### FAQ.3: Who are the authors and maintainers of these guidelines? The initial primary authors and maintainers are Bjarne Stroustrup and Herb Sutter, and the guidelines so far were developed with contributions from experts at CERN, Microsoft, Morgan Stanley, and several other organizations. At the time of their release, the guidelines are in a "0.6" state, and contributions are welcome. As Stroustrup said in his announcement: "We need help!" -### FAQ.4: How can I contribute? +### FAQ.4: How can I contribute? See [CONTRIBUTING.md](https://github.com/isocpp/CppCoreGuidelines/blob/master/CONTRIBUTING.md). We appreciate volunteer help! -### FAQ.5: How can I become an editor/maintainer? +### FAQ.5: How can I become an editor/maintainer? By contributing a lot first and having the consistent quality of your contributions recognized. See [CONTRIBUTING.md](https://github.com/isocpp/CppCoreGuidelines/blob/master/CONTRIBUTING.md). We appreciate volunteer help! -### FAQ.6: Have these guidelines been approved by the ISO C++ standards committee? Do they represent the consensus of the committee? +### FAQ.6: Have these guidelines been approved by the ISO C++ standards committee? Do they represent the consensus of the committee? No. These guidelines are outside the standard. They are intended to serve the standard, and be maintained as current guidelines about how to use the current Standard C++ effectively. We aim to keep them in sync with the standard as that is evolved by the committee. -### FAQ.7: If these guidelines are not approved by the committee, why are they under `github.com/isocpp`? +### FAQ.7: If these guidelines are not approved by the committee, why are they under `github.com/isocpp`? Because `isocpp` is the Standard C++ Foundation; the committee's repositories are under [github.com/*cplusplus*](https://github.com/cplusplus). Some neutral organization has to own the copyright and license to make it clear this is not being dominated by any one person or vendor. The natural entity is the Foundation, which exists to promote the use and up-to-date understanding of modern Standard C++ and the work of the committee. This follows the same pattern that isocpp.org did for the [C++ FAQ](https://isocpp.org/faq), which was initially the work of Bjarne Stroustrup, Marshall Cline, and Herb Sutter and contributed to the open project in the same way. -### FAQ.8: Will there be a C++98 version of these Guidelines? A C++11 version? +### FAQ.8: Will there be a C++98 version of these Guidelines? A C++11 version? No. These guidelines are about how to best use modern standard C++ and write code assuming you have a modern conforming compiler. -### FAQ.9: Do these guidelines propose new language features? +### FAQ.9: Do these guidelines propose new language features? No. These guidelines are about how to best use modern Standard C++, and they limit themselves to recommending only those features. -### FAQ.10: What version of Markdown do these guidelines use? +### FAQ.10: What version of Markdown do these guidelines use? These coding standards are written using [CommonMark](http://commonmark.org), and `` HTML anchors. @@ -22138,58 +22138,58 @@ Avoid other HTML tags and other extensions. Note: We are not yet consistent with this style. -### FAQ.50: What is the GSL (guidelines support library)? +### FAQ.50: What is the GSL (guidelines support library)? The GSL is the small set of types and aliases specified in these guidelines. As of this writing, their specification herein is too sparse; we plan to add a WG21-style interface specification to ensure that different implementations agree, and to propose as a contribution for possible standardization, subject as usual to whatever the committee decides to accept/improve/alter/reject. -### FAQ.51: Is [github.com/Microsoft/GSL](https://github.com/Microsoft/GSL) the GSL? +### FAQ.51: Is [github.com/Microsoft/GSL](https://github.com/Microsoft/GSL) the GSL? No. That is just a first implementation contributed by Microsoft. Other implementations by other vendors are encouraged, as are forks of and contributions to that implementation. As of this writing one week into the public project, at least one GPLv3 open-source implementation already exists. We plan to produce a WG21-style interface specification to ensure that different implementations agree. -### FAQ.52: Why not supply an actual GSL implementation in/with these guidelines? +### FAQ.52: Why not supply an actual GSL implementation in/with these guidelines? We are reluctant to bless one particular implementation because we do not want to make people think there is only one, and inadvertently stifle parallel implementations. And if these guidelines included an actual implementation, then whoever contributed it could be mistakenly seen as too influential. We prefer to follow the long-standing approach of the committee, namely to specify interfaces, not implementations. But at the same time we want at least one implementation available; we hope for many. -### FAQ.53: Why weren't the GSL types proposed through Boost? +### FAQ.53: Why weren't the GSL types proposed through Boost? Because we want to use them immediately, and because they are temporary in that we want to retire them as soon as types that fill the same needs exist in the standard library. -### FAQ.54: Has the GSL (guidelines support library) been approved by the ISO C++ standards committee? +### FAQ.54: Has the GSL (guidelines support library) been approved by the ISO C++ standards committee? No. The GSL exists only to supply a few types and aliases that are not currently in the standard library. If the committee decides on standardized versions (of these or other types that fill the same need) then they can be removed from the GSL. -### FAQ.55: If you're using the standard types where available, why is the GSL `span` different from the `string_view` in the Library Fundamentals 1 Technical Specification and C++17 Working Paper? Why not just use the committee-approved `string_view`? +### FAQ.55: If you're using the standard types where available, why is the GSL `span` different from the `string_view` in the Library Fundamentals 1 Technical Specification and C++17 Working Paper? Why not just use the committee-approved `string_view`? The consensus on the taxonomy of views for the C++ Standard Library was that "view" means "read-only", and "span" means "read/write". If you only need a read-only view of characters that does not need guaranteed bounds-checking and you have C++17, use C++17 `std::string_view`. Otherwise, if you need a read-write view that does not need guaranteed bounds-checking and you have C++20, use C++20 `std::span`. Otherwise, use `gsl::span`. -### FAQ.56: Is `owner` the same as the proposed `observer_ptr`? +### FAQ.56: Is `owner` the same as the proposed `observer_ptr`? No. `owner` owns, is an alias, and can be applied to any indirection type. The main intent of `observer_ptr` is to signify a *non*-owning pointer. -### FAQ.57: Is `stack_array` the same as the standard `array`? +### FAQ.57: Is `stack_array` the same as the standard `array`? No. `stack_array` is guaranteed to be allocated on the stack. Although a `std::array` contains its storage directly inside itself, the `array` object can be put anywhere, including the heap. -### FAQ.58: Is `dyn_array` the same as `vector` or the proposed `dynarray`? +### FAQ.58: Is `dyn_array` the same as `vector` or the proposed `dynarray`? No. `dyn_array` is a container, like `vector`, but it is not resizable; its size is fixed at runtime when it is constructed. It is a safe way to refer to a dynamically "heap"-allocated fixed-size array. Unlike `vector`, it is intended to replace array-`new[]`. Unlike the `dynarray` that has been proposed in the committee, this does not anticipate compiler/language magic to somehow allocate it on the stack when it is a member of an object that is allocated on the stack; it simply refers to a "dynamic" or heap-based array. -### FAQ.59: Is `Expects` the same as `assert`? +### FAQ.59: Is `Expects` the same as `assert`? No. It is a placeholder for language support for contract preconditions. -### FAQ.60: Is `Ensures` the same as `assert`? +### FAQ.60: Is `Ensures` the same as `assert`? No. It is a placeholder for language support for contract postconditions. -# Appendix A: Libraries +# Appendix A: Libraries This section lists recommended libraries, and explicitly recommends a few. ??? Suitable for the general guide? I think not ??? -# Appendix B: Modernizing code +# Appendix B: Modernizing code Ideally, we follow all rules in all code. Realistically, we have to deal with a lot of old code: @@ -22222,7 +22222,7 @@ Here are some (very general) ideas: * The ideal is "just upgrade everything." That gives the most benefits for the shortest total time. In most circumstances, it is also impossible. -* We could convert a code base module for module, but any rules that affects interfaces (especially ABIs), such as [use `span`](#SS-views), cannot be done on a per-module basis. +* We could convert a code base module for module, but any rules that affects interfaces (especially ABIs), such as [use `span`](#ss-views), cannot be done on a per-module basis. * We could convert code "bottom up" starting with the rules we estimate will give the greatest benefits and/or the least trouble in a given code base. * We could start by focusing on the interfaces, e.g., make sure that no resources are lost and no pointer is misused. This would be a set of changes across the whole code base, but would most likely have huge benefits. @@ -22234,12 +22234,12 @@ The guidelines are not a random set of unrelated rules where you can randomly pi We would dearly love to hear about experience and about tools used. Modernization can be much faster, simpler, and safer when supported with analysis tools and even code transformation tools. -# Appendix C: Discussion +# Appendix C: Discussion This section contains follow-up material on rules and sets of rules. In particular, here we present further rationale, longer examples, and discussions of alternatives. -### Discussion: Define and initialize data members in the order of member declaration +### Discussion: Define and initialize data members in the order of member declaration Data members are always initialized in the order they are declared in the class definition, so write them in that order in the constructor initialization list. Writing them in a different order just makes the code confusing because it won't run in the order you see, and that can make it hard to see order-dependent bugs. @@ -22265,11 +22265,11 @@ If the class definition and the constructor body are in separate files, the long [\[Cline99\]](#Cline99) §22.03-11, [\[Dewhurst03\]](#Dewhurst03) §52-53, [\[Koenig97\]](#Koenig97) §4, [\[Lakos96\]](#Lakos96) §10.3.5, [\[Meyers97\]](#Meyers97) §13, [\[Murray93\]](#Murray93) §2.1.3, [\[Sutter00\]](#Sutter00) §47 -### Discussion: Use of `=`, `{}`, and `()` as initializers +### Discussion: Use of `=`, `{}`, and `()` as initializers ??? -### Discussion: Use a factory function if you need "virtual behavior" during initialization +### Discussion: Use a factory function if you need "virtual behavior" during initialization If your design wants virtual dispatch into a derived class from a base class constructor or destructor for functions like `f` and `g`, you need other techniques, such as a post-constructor -- a separate member function the caller must invoke to complete initialization, which can safely call `f` and `g` because in member functions virtual calls behave normally. Some techniques for this are shown in the References. Here's a non-exhaustive list of options: @@ -22346,7 +22346,7 @@ In summary, no post-construction technique is perfect. The worst techniques dodg **References**: [\[Alexandrescu01\]](#Alexandrescu01) §3, [\[Boost\]](#Boost), [\[Dewhurst03\]](#Dewhurst03) §75, [\[Meyers97\]](#Meyers97) §46, [\[Stroustrup00\]](#Stroustrup00) §15.4.3, [\[Taligent94\]](#Taligent94) -### Discussion: Make base class destructors public and virtual, or protected and non-virtual +### Discussion: Make base class destructors public and virtual, or protected and non-virtual Should destruction behave virtually? That is, should destruction through a pointer to a `base` class be allowed? If yes, then `base`'s destructor must be public in order to be callable, and virtual, otherwise calling it results in undefined behavior. Otherwise, it should be protected so that only derived classes can invoke it in their own destructors, and non-virtual since it doesn't need to behave virtually. @@ -22417,11 +22417,11 @@ In general, however, avoid concrete base classes (see Item 35). For example, `un **References**: [\[SuttAlex05\]](#SuttAlex05) Item 50, [\[Cargill92\]](#Cargill92) pp. 77-79, 207, [\[Cline99\]](#Cline99) §21.06, 21.12-13, [\[Henricson97\]](#Henricson97) pp. 110-114, [\[Koenig97\]](#Koenig97) Chapters 4, 11, [\[Meyers97\]](#Meyers97) §14, [\[Stroustrup00\]](#Stroustrup00) §12.4.2, [\[Sutter02\]](#Sutter02) §27, [\[Sutter04\]](#Sutter04) §18 -### Discussion: Usage of noexcept +### Discussion: Usage of noexcept ??? -### Discussion: Destructors, deallocation, and swap must never fail +### Discussion: Destructors, deallocation, and swap must never fail Never allow an error to be reported from a destructor, a resource deallocation function (e.g., `operator delete`), or a `swap` function using `throw`. It is nearly impossible to write useful code if these operations can fail, and even if something does go wrong it nearly never makes any sense to retry. Specifically, types whose destructors might throw an exception are flatly forbidden from use with the C++ Standard Library. Most destructors are now implicitly `noexcept` by default. @@ -22511,7 +22511,7 @@ When using exceptions as your error handling mechanism, always document this beh **References**: [\[SuttAlex05\]](#SuttAlex05) Item 51; [\[C++03\]](#Cplusplus03) §15.2(3), §17.4.4.8(3), [\[Meyers96\]](#Meyers96) §11, [\[Stroustrup00\]](#Stroustrup00) §14.4.7, §E.2-4, [\[Sutter00\]](#Sutter00) §8, §16, [\[Sutter02\]](#Sutter02) §18-19 -## Define Copy, move, and destroy consistently +## Define Copy, move, and destroy consistently ##### Reason @@ -22600,16 +22600,16 @@ In a class holding a reference, you likely need to write the copy constructor an Resource management rule summary: -* [Provide strong resource safety; that is, never leak anything that you think of as a resource](#Cr-safety) -* [Never return or throw while holding a resource not owned by a handle](#Cr-never) -* [A "raw" pointer or reference is never a resource handle](#Cr-raw) -* [Never let a pointer outlive the object it points to](#Cr-outlive) -* [Use templates to express containers (and other resource handles)](#Cr-templates) -* [Return containers by value (relying on move or copy elision for efficiency)](#Cr-value-return) -* [If a class is a resource handle, it needs a constructor, a destructor, and copy and/or move operations](#Cr-handle) -* [If a class is a container, give it an initializer-list constructor](#Cr-list) +* [Provide strong resource safety; that is, never leak anything that you think of as a resource](#cr-safety) +* [Never return or throw while holding a resource not owned by a handle](#cr-never) +* [A "raw" pointer or reference is never a resource handle](#cr-raw) +* [Never let a pointer outlive the object it points to](#cr-outlive) +* [Use templates to express containers (and other resource handles)](#cr-templates) +* [Return containers by value (relying on move or copy elision for efficiency)](#cr-value-return) +* [If a class is a resource handle, it needs a constructor, a destructor, and copy and/or move operations](#cr-handle) +* [If a class is a container, give it an initializer-list constructor](#cr-list) -### Discussion: Provide strong resource safety; that is, never leak anything that you think of as a resource +### Discussion: Provide strong resource safety; that is, never leak anything that you think of as a resource ##### Reason @@ -22627,7 +22627,7 @@ Prevent leaks. Leaks can lead to performance degradation, mysterious error, syst // ... }; -This class is a resource handle. It manages the lifetime of the `T`s. To do so, `Vector` must define or delete [the copy, move, and destruction operations](#Rc-five). +This class is a resource handle. It manages the lifetime of the `T`s. To do so, `Vector` must define or delete [the copy, move, and destruction operations](#rc-five). ##### Example @@ -22637,7 +22637,7 @@ This class is a resource handle. It manages the lifetime of the `T`s. To do so, The basic technique for preventing leaks is to have every resource owned by a resource handle with a suitable destructor. A checker can find "naked `new`s". Given a list of C-style allocation functions (e.g., `fopen()`), a checker can also find uses that are not managed by a resource handle. In general, "naked pointers" can be viewed with suspicion, flagged, and/or analyzed. A complete list of resources cannot be generated without human input (the definition of "a resource" is necessarily too general), but a tool can be "parameterized" with a resource list. -### Discussion: Never return or throw while holding a resource not owned by a handle +### Discussion: Never return or throw while holding a resource not owned by a handle ##### Reason @@ -22682,7 +22682,7 @@ A checker probably must rely on a human-provided list of resources. For starters, we know about the standard-library containers, `string`, and smart pointers. The use of `span` and `string_view` should help a lot (they are not resource handles). -### Discussion: A "raw" pointer or reference is never a resource handle +### Discussion: A "raw" pointer or reference is never a resource handle ##### Reason @@ -22692,7 +22692,7 @@ To be able to distinguish owners from views. This is independent of how you "spell" pointer: `T*`, `T&`, `Ptr` and `Range` are not owners. -### Discussion: Never let a pointer outlive the object it points to +### Discussion: Never let a pointer outlive the object it points to ##### Reason @@ -22723,7 +22723,7 @@ The `string`s of `v` are destroyed upon exit from `bad()` and so is `v` itself. Most compilers already warn about simple cases and have the information to do more. Consider any pointer returned from a function suspect. Use containers, resource handles, and views (e.g., `span` known not to be resource handles) to lower the number of cases to be examined. For starters, consider every class with a destructor as resource handle. -### Discussion: Use templates to express containers (and other resource handles) +### Discussion: Use templates to express containers (and other resource handles) ##### Reason @@ -22737,13 +22737,13 @@ To provide statically type-safe manipulation of elements. int sz; }; -### Discussion: Return containers by value (relying on move or copy elision for efficiency) +### Discussion: Return containers by value (relying on move or copy elision for efficiency) ##### Reason To simplify code and eliminate a need for explicit memory management. To bring an object into a surrounding scope, thereby extending its lifetime. -**See also**: [F.20, the general item about "out" output values](#Rf-out) +**See also**: [F.20, the general item about "out" output values](#rf-out) ##### Example @@ -22756,13 +22756,13 @@ To simplify code and eliminate a need for explicit memory management. To bring a ##### Exception -See the Exceptions in [F.20](#Rf-out). +See the Exceptions in [F.20](#rf-out). ##### Enforcement Check for pointers and references returned from functions and see if they are assigned to resource handles (e.g., to a `unique_ptr`). -### Discussion: If a class is a resource handle, it needs a constructor, a destructor, and copy and/or move operations +### Discussion: If a class is a resource handle, it needs a constructor, a destructor, and copy and/or move operations ##### Reason @@ -22785,9 +22785,9 @@ Now `Named` has a default constructor, a destructor, and efficient copy and move ##### Enforcement -In general, a tool cannot know if a class is a resource handle. However, if a class has some of [the default operations](#SS-ctor), it should have all, and if a class has a member that is a resource handle, it should be considered as resource handle. +In general, a tool cannot know if a class is a resource handle. However, if a class has some of [the default operations](#ss-ctor), it should have all, and if a class has a member that is a resource handle, it should be considered as resource handle. -### Discussion: If a class is a container, give it an initializer-list constructor +### Discussion: If a class is a container, give it an initializer-list constructor ##### Reason @@ -22807,7 +22807,7 @@ It is common to need an initial set of elements. When is a class a container? ??? -# Appendix D: Supporting tools +# Appendix D: Supporting tools This section contains a list of tools that directly support adoption of the C++ Core Guidelines. This list is not intended to be an exhaustive list of tools that are helpful in writing good C++ code. If a tool is designed specifically to support and links to the C++ Core Guidelines it is a candidate for inclusion. @@ -22820,7 +22820,7 @@ Clang-tidy has a set of rules that specifically enforce the C++ Core Guidelines. The Microsoft compiler's C++ code analysis contains a set of rules specifically aimed at enforcement of the C++ Core Guidelines. -# Glossary +# Glossary A relatively informal definition of terms used in the guidelines (based off the glossary in [Programming: Principles and Practice using C++](http://www.stroustrup.com/programming.html)) @@ -22969,7 +22969,7 @@ In particular, an object of a regular type can be copied and the result of a cop * *virtual function*: a member function that can be overridden in a derived class. * *word*: a basic unit of memory in a computer, often the unit used to hold an integer. -# To-do: Unclassified proto-rules +# To-do: Unclassified proto-rules This is our to-do list. Eventually, the entries will become rules or parts of rules. diff --git a/scripts/hunspell/isocpp.dic b/scripts/hunspell/isocpp.dic index 5dd1c315b..b5c2229db 100644 --- a/scripts/hunspell/isocpp.dic +++ b/scripts/hunspell/isocpp.dic @@ -73,6 +73,7 @@ cbegin CComPtr cend cerr +charp chrono cin Clang's @@ -104,6 +105,7 @@ CppCoreCheck cppcoreguidelines cppreference CRTP +cr cst cstdarg cstdio @@ -241,6 +243,7 @@ JSF jthread Juhl knr +knuth Koenig97 Lakos Lakos96 @@ -261,6 +264,7 @@ m1 m2 m3 macros2 +macros3 malloc mallocfree Mathematizing @@ -374,16 +378,17 @@ ptr2 q2 qqq qsort -R0 +r0 r2 +ra raii -Rc -Rclib -Rcon -Rconc -Rconst +rc +rclib +rcon +rconc +rconst rcoro -Rcpl +rcpl Rec2 refactor refactored @@ -395,7 +400,7 @@ reimplement reinterpretcast Reis Reis's -Renum +renum reseat reseating reseats @@ -405,17 +410,21 @@ rethrowing retryable *Re-usability reusability -Ri -Rl -Rnr -Ro +rf +rh +ri +rio +rl +rnr +ro Rouquette -Rp -Rper +rp +rper rr -Rsl -Rstr +rsl +rstr RTTI +ru rvalue rvalues RVO @@ -426,7 +435,7 @@ s2 s3 Sarkar scanf -Sd +sd SEI semiregular SemiRegular @@ -453,7 +462,8 @@ specialization2 spinlock splonk splunk -SScp +ss +sscp stdarg stdlib Stepanov