Repository: isocpp/CppCoreGuidelines
Branch: master
Commit: 431d25dc7710
Files: 31
Total size: 1.8 MB
Directory structure:
gitextract_y8p6tgzy/
├── .github/
│ └── workflows/
│ ├── build.yml
│ └── jekyll-gh-pages.yml
├── .gitignore
├── .travis.yml
├── CONTRIBUTING.md
├── CppCoreGuidelines.md
├── LICENSE
├── README.md
├── SECURITY.md
├── _config.yml
├── _includes/
│ ├── head.html
│ └── sidebar.html
├── _layouts/
│ └── default.html
├── docs/
│ ├── dyn_array.md
│ └── gsl-intro.md
├── index.html
├── params.json
├── public/
│ └── css/
│ ├── custom.css
│ ├── hyde.css
│ └── poole.css
├── scripts/
│ ├── Makefile
│ ├── hunspell/
│ │ ├── en_US.aff
│ │ ├── en_US.dic
│ │ └── isocpp.dic
│ ├── nodejs/
│ │ ├── package.json
│ │ └── remark/
│ │ └── .remarkrc
│ └── python/
│ ├── Makefile.in
│ ├── cpplint.py
│ ├── cpplint_wrap.py
│ └── md-split.py
└── talks/
└── README.md
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/workflows/build.yml
================================================
name: build
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- name: Install Hunspell
run: |
sudo apt-get update
sudo apt-get install hunspell
- name: Run cd scripts; make -k
run: cd scripts; make -k
- name: Run cd ..
run: cd ..
================================================
FILE: .github/workflows/jekyll-gh-pages.yml
================================================
# Sample workflow for building and deploying a Jekyll site to GitHub Pages
name: Deploy Jekyll with GitHub Pages dependencies preinstalled
on:
# Runs on pushes targeting the default branch
push:
branches: ["master"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Setup Pages
uses: actions/configure-pages@v5
- name: Build with Jekyll
uses: actions/jekyll-build-pages@v1
with:
source: ./
destination: ./_site
- name: Upload artifact
uses: actions/upload-pages-artifact@v4
# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
================================================
FILE: .gitignore
================================================
scripts/build
scripts/nodesjs/build
node_modules
_site
scripts/python/__pycache__
scripts/python/*.pyc
# VS Code
.vs/
# MacOS-specific
.DS_Store
================================================
FILE: .travis.yml
================================================
# This is the configuration for Travis CI, a free github-integrated service that runs this script for each pull request (if configured)
# provides gcc, clang, make, scons, cmake
language: c++
# alternatives: gcc, clang, or both (as yaml list)
compiler: clang
addons:
apt:
packages:
- hunspell
install:
-
script:
- cd scripts; make -k
- cd ..
notifications:
email: false
================================================
FILE: CONTRIBUTING.md
================================================
## Contributing to the C++ Core Guidelines
>"Within C++ is a smaller, simpler, safer language struggling to get out."
>-- Bjarne Stroustrup
The C++ Core Guidelines are a collaborative effort led by Bjarne Stroustrup, much like the C++ language itself. They are the result of many
person-years of discussion and design across a number of organizations. Their design encourages general applicability and broad adoption but
they can be freely copied and modified to meet your organization's needs.
We encourage contributions to the C++ Core Guidelines in a number of ways:
- **Individual feedback** Are you a developer who is passionate about your code? Join the discussion in
[Issues](https://github.com/isocpp/CppCoreGuidelines/issues). We want to know which rules resonate with you and which don't. Were any rules
inordinately difficult to apply? Does your compiler vendor's Guidelines Support Library (e.g.,
[Microsoft's implementation of the GSL](https://github.com/microsoft/gsl)) suit your needs in adopting these guidelines?
- **Organizational adoption** While the guidelines are designed to be broadly adoptable they are also intended to be modified to fit your
organization's particular needs. We encourage your organization to fork this repo and create your own copy of these guidelines with changes
that reflect your needs. We suggest that you make it clear in the title of your guidelines that these are your organization's fork of the
guidelines and that you provide a link back to the original set of [guidelines](https://github.com/isocpp/CppCoreGuidelines). And if any of
your local changes are appropriate to pull back into the original guidelines, please open an
[Issue](https://github.com/isocpp/CppCoreGuidelines/issues) which can lead to a pull request.
- **Maintain the Guidelines** The C++ Core Guidelines were created from a wealth of knowledge spread across a number of organizations
worldwide. If you or your organization is passionate about helping to create the guidelines, consider becoming an editor or maintainer. If
you're a C++ expert who is serious about participating, please
[email coreguidelines@isocpp.org](mailto:coreguidelines@isocpp.org?subject=Maintain%20the%20C++%20Code%20Guidelines).
## Contributor License Agreement
By contributing content to the C++ Core Guidelines (i.e., submitting a pull request for inclusion in this repository) you agree with the
[Standard C++ Foundation](https://isocpp.org/about) [Terms of Use](https://isocpp.org/home/terms-of-use), especially all of the terms specified
regarding Copyright and Patents.
- You warrant that your material is original, or you have the right to contribute it.
- With respect to the material that you own, you grant a worldwide, non-exclusive, irrevocable, transferable, and royalty-free license to your contributed
material to Standard C++ Foundation to display, reproduce, perform, distribute, and create derivative works of that material for commercial or
non-commercial use. With respect to any other material you contribute, such material must be under a license sufficient to allow Standard C++ Foundation
to display, reproduce, perform, distribute, and create derivative works of that material for commercial or non-commercial use.
- You agree that, if your contributed material is subsequently reflected in the ISO/IEC C++ standard in any form, it will be subject to all ISO/IEC JTC
1 policies including [copyrights](http://www.iso.org/iso/home/policies.htm),
[patents](http://www.iso.org/iso/home/standards_development/governance_of_technical_work/patents.htm), and
[procedures](http://www.itscj.ipsj.or.jp/sc29/29w7proc.htm); please direct any questions about these policies to the
[ISO Central Secretariat](http://www.iso.org/iso/home/about.htm).
## Pull requests
We welcome pull requests for scoped changes to the guidelines--bug fixes in
examples, clarifying ambiguous text, etc. Significant changes should first be
discussed in the [Issues](https://github.com/isocpp/CppCoreGuidelines/issues)
and the Issue number must be included in the pull request. For
guideline-related changes, please specify the rule number in your Issue and/or
Pull Request.
Changes should be made in a child commit of a recent commit in the master
branch. If you are making many small changes, please create separate PRs to
minimize merge issues.
### Document Style Guidelines
Documents in this repository are written in an unspecific flavor of Markdown,
which leaves some ambiguity for formatting text. We ask that pull requests
maintain the following style guidelines, though we are aware that the document
may not already be consistent.
#### Indentation
Code and nested text should use multiples of 4 spaces of indentation, and no
tab characters, like so:
void func(const int x)
{
std::cout << x << '\n';
}
#### Code Blocks
Please use 4-space indentation to trigger code parsing, rather than [fenced code blocks](https://help.github.com/articles/github-flavored-markdown/#fenced-code-blocks) or any other style, like so:
This is some document text, with an example below:
void func()
{
std::cout << "This is code.\n";
}
#### Document style decisions
We've discussed and made decisions on a number of document style. Please do not open PRs that revisit these stylistic points:
- The CppCoreGuidelines.md file is a single GH-flavored Markdown file. It is not split into separate chapters.
- We do not use syntax highlighting in the Core Guidelines. See PRs #33, #96, #328, and #779. If you want syntax highlighting you
can either view the "pretty" version at http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines or do your own post-processing.
- We're sticking with the ASCII character set. We do not use Unicode em-dashes, Unicode spaces, or pretty quotes. Lots of people edit this file with their various text editors. ASCII is simple and universally understood.
### Update dictionary
Code samples in the guidelines are run through a spelling checker. Be sure to add new class and variable names to [scripts/hunspell/isocpp.dic](https://github.com/isocpp/CppCoreGuidelines/blob/master/scripts/hunspell/isocpp.dic).
### Miscellaneous
To avoid line-ending issues, please set `autocrlf = input` and `whitespace = cr-at-eol` in your git configuration.
================================================
FILE: CppCoreGuidelines.md
================================================
# C++ Core Guidelines
Jul 8, 2025
Editors:
* [Bjarne Stroustrup](https://www.stroustrup.com)
* [Herb Sutter](https://herbsutter.com/)
This is a living document under continuous improvement.
Had it been an open-source (code) project, this would have been release 0.8.
Copying, use, modification, and creation of derivative works from this project is licensed under an MIT-style license.
Contributing to this project requires agreeing to a Contributor License. See the accompanying [LICENSE](https://github.com/isocpp/CppCoreGuidelines/blob/master/LICENSE) file for details.
We make this project available to "friendly users" to use, copy, modify, and derive from, hoping for constructive input.
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).
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)
* [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)
* [GSL: Guidelines support library](#s-gsl)
* [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)
* `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)
* `concept`:
[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)
* 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)
* destructor:
[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)
* `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-???)
* 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)
* `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)
* lambda expression:
[when to use](#ss-lambdas)
* operator:
[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)
* `static_assert`:
[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)
* `template`:
[abstraction](#rt-raise) --
[containers](#rt-cont) --
[concepts](#rt-concepts)
* `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)
You can look at design concepts used to express the rules:
* assertion: ???
* error: ???
* exception: exception guarantee (???)
* failure: ???
* invariant: ???
* leak: ???
* library: ???
* precondition: ???
* postcondition: ???
* resource: ???
# 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.
By "modern C++" we mean effective use of the ISO C++ standard (currently C++20, but almost all of our recommendations also apply to C++17, C++14 and C++11).
In other words, what would you like your code to look like in 5 years' time, given that you can start now? In 10 years' time?
The guidelines are focused on relatively high-level issues, such as interfaces, resource management, memory management, and concurrency.
Such rules affect application architecture and library design.
Following the rules will lead to code that is statically type safe, has no resource leaks, and catches many more programming logic errors than is common in code today.
And it will run fast -- you can afford to do things right.
We are less concerned with low-level issues, such as naming conventions and indentation style.
However, no topic that can help a programmer is out of bounds.
Our initial set of rules emphasizes safety (of various forms) and simplicity.
They might very well be too strict.
We expect to have to introduce more exceptions to better accommodate real-world needs.
We also need more rules.
You will find some of the rules contrary to your expectations or even contrary to your experience.
If we haven't suggested you change your coding style in any way, we have failed!
Please try to verify or disprove rules!
In particular, we'd really like to have some of our rules backed up with measurements or better examples.
You will find some of the rules obvious or even trivial.
Please remember that one purpose of a guideline is to help someone who is less experienced or coming from a different background or language to get up to speed.
Many of the rules are designed to be supported by an analysis tool.
Violations of rules will be flagged with references (or links) to the relevant rule.
We do not expect you to memorize all the rules before trying to write code.
One way of thinking about these guidelines is as a specification for tools that happens to be readable by humans.
The rules are meant for gradual introduction into a code base.
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
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
All C++ programmers. This includes [programmers who might consider C](#s-cpl).
## 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.
We do not suffer the delusion that every one of these rules can be effectively applied to every code base. Upgrading old systems is hard. However, we do believe that a program that uses a rule is less error-prone and more maintainable than one that does not. Often, rules also lead to faster/easier initial development.
As far as we can tell, these rules lead to code that performs as well or better than older, more conventional techniques; they are meant to follow the zero-overhead principle ("what you don't use, you don't pay for" or "when you use an abstraction mechanism appropriately, you get at least as good performance as if you had handcoded using lower-level language constructs").
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!
Take the time to understand the implications of a guideline rule on your program.
These guidelines are designed according to the "subset of superset" principle ([Stroustrup05](#Stroustrup05)).
They do not simply define a subset of C++ to be used (for reliability, safety, performance, or whatever).
Instead, they strongly recommend the use of a few simple "extensions" ([library components](#gsl-guidelines-support-library))
that make the use of the most error-prone features of C++ redundant, so that they can be banned (in our set of rules).
The rules emphasize static type safety and resource safety.
For that reason, they emphasize possibilities for range checking, for avoiding dereferencing `nullptr`, for avoiding dangling pointers, and the systematic use of exceptions (via RAII).
Partly to achieve that and partly to minimize obscure code as a source of errors, the rules also emphasize simplicity and the hiding of necessary complexity behind well-specified interfaces.
Many of the rules are prescriptive.
We are uncomfortable with rules that simply state "don't do that!" without offering an alternative.
One consequence of that is that some rules can be supported only by heuristics, rather than precise and mechanically verifiable checks.
Other rules articulate general principles. For these more general rules, more detailed and specific rules provide partial checking.
These guidelines address the core of C++ and its use.
We expect that most large organizations, specific application areas, and even large projects will need further rules, possibly further restrictions, and further library support.
For example, hard-real-time programmers typically can't use free store (dynamic memory) freely and will be restricted in their choice of libraries.
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).
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
The rules are not intended to be minimal or orthogonal.
In particular, general rules can be simple, but unenforceable.
Also, it is often hard to understand the implications of a general rule.
More specialized rules are often easier to understand and to enforce, but without general rules, they would just be a long list of special cases.
We provide rules aimed at helping novices as well as rules supporting expert use.
Some rules can be completely enforced, but others are based on heuristics.
These rules are not meant to be read serially, like a book.
You can browse through them using the links.
However, their main intended use is to be targets for tools.
That is, a tool looks for violations and the tool returns links to violated rules.
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).
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.
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.
For the final word on language definition issues, including every exception to general rules and every feature, see the ISO C++ standard.
The rules are not intended to force you to write in an impoverished subset of C++.
They are *emphatically* not meant to define a, say, Java-like subset of C++.
They are not meant to define a single "one true C++" language.
We value expressiveness and uncompromised performance.
The rules are not value-neutral.
They are meant to make code simpler and more correct/safer than most existing C++ code, without loss of performance.
They are meant to inhibit perfectly valid C++ code that correlates with errors, spurious complexity, and poor performance.
The rules are not precise to the point where a person (or machine) can follow them without thinking.
The enforcement parts try to be that, but we would rather leave a rule or a definition a bit vague
and open to interpretation than specify something precisely and wrong.
Sometimes, precision comes only with time and experience.
Design is not (yet) a form of Math.
The rules are not perfect.
A rule can do harm by prohibiting something that is useful in a given situation.
A rule can do harm by failing to prohibit something that enables a serious error in a given situation.
A rule can do a lot of harm by being vague, ambiguous, unenforceable, or by enabling every solution to a problem.
It is impossible to completely meet the "do no harm" criteria.
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
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.
* But we want lots of rules, and we want rules that everybody can use.
* But different people have different needs.
* But people don't like to read lots of rules.
* But people can't remember many rules.
So, we need subsetting to meet a variety of needs.
* But arbitrary subsetting leads to chaos.
We want guidelines that help a lot of people, make code more uniform, and strongly encourage people to modernize their code.
We want to encourage best practices, rather than leave all to individual choices and management pressures.
The ideal is to use all rules; that gives the greatest benefits.
This adds up to quite a few dilemmas.
We try to resolve those using tools.
Each rule has an **Enforcement** section listing ideas for enforcement.
Enforcement might be done by code review, by static analysis, by compiler, or by run-time checks.
Wherever possible, we prefer "mechanical" checking (humans are slow, inaccurate, and bore easily) and static checking.
Run-time checks are suggested only rarely where no alternative exists; we do not want to introduce "distributed bloat".
Where appropriate, we label a rule (in the **Enforcement** sections) with the name of groups of related rules (called "profiles").
A rule can be part of several profiles, or none.
For a start, we have a few profiles corresponding to common needs (desires, ideals):
* **type**: No type violations (reinterpreting a `T` as a `U` through casts, unions, or varargs)
* **bounds**: No bounds violations (accessing beyond the range of an array)
* **lifetime**: No leaks (failing to `delete` or multiple `delete`) and no access to invalid objects (dereferencing `nullptr`, using a dangling reference).
The profiles are intended to be used by tools, but also serve as an aid to the human reader.
We do not limit our comment in the **Enforcement** sections to things we know how to enforce; some comments are mere wishes that might inspire some tool builder.
Tools that implement these rules shall respect the following syntax to explicitly suppress a rule:
[[gsl::suppress("tag")]]
and optionally with a message (following usual C++11 standard attribute syntax):
[[gsl::suppress("tag", justification: "message")]]
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
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.
* `"message"` is a string literal
## In.struct: The structure of this document
Each rule (guideline, suggestion) can have several parts:
* The rule itself -- e.g., **no naked `new`**
* A rule reference number -- e.g., **C.7** (the 7th rule related to classes).
Since the major sections are not inherently ordered, we use letters as the first part of a rule reference "number".
We leave gaps in the numbering to minimize "disruption" when we add or remove rules.
* **Reason**s (rationales) -- because programmers find it hard to follow rules they don't understand
* **Example**s -- because rules are hard to understand in the abstract; can be positive or negative
* **Alternative**s -- for "don't do this" rules
* **Exception**s -- we prefer simple general rules. However, many rules apply widely, but not universally, so exceptions must be listed
* **Enforcement** -- ideas about how the rule might be checked "mechanically"
* **See also**s -- references to related rules and/or further discussion (in this document or elsewhere)
* **Note**s (comments) -- something that needs saying that doesn't fit the other classifications
* **Discussion** -- references to more extensive rationale and/or examples placed outside the main lists of rules
Some rules are hard to check mechanically, but they all meet the minimal criteria that an expert programmer can spot many violations without too much trouble.
We hope that "mechanical" tools will improve with time to approximate what such an expert programmer notices.
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.
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.
Examples are written to illustrate rules.
* Examples are not intended to be production quality or to cover all tutorial dimensions.
For example, many examples are language-technical and use names like `f`, `base`, and `x`.
* We try to ensure that "good" examples follow the Core Guidelines.
* Comments are often illustrating rules where they would be unnecessary and/or distracting in "real code."
* We assume knowledge of the standard library. For example, we use plain `vector` rather than `std::vector`.
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)
* [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)
* [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)
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
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)
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
##### Reason
Compilers don't read comments (or design documents) and neither do many programmers (consistently).
What is expressed in code has defined semantics and can (in principle) be checked by compilers and other tools.
##### Example
class Date {
public:
Month month() const; // do
int month(); // don't
// ...
};
The first declaration of `month` is explicit about returning a `Month` and about not modifying the state of the `Date` object.
The second version leaves the reader guessing and opens more possibilities for uncaught bugs.
##### Example, bad
This loop is a restricted form of `std::find`:
void f(vector& v)
{
string val;
cin >> val;
// ...
int index = -1; // bad, plus should use gsl::index
for (int i = 0; i < v.size(); ++i) {
if (v[i] == val) {
index = i;
break;
}
}
// ...
}
##### Example, good
A much clearer expression of intent would be:
void f(vector& v)
{
string val;
cin >> val;
// ...
auto p = find(begin(v), end(v), val); // better
// ...
}
A well-designed library expresses intent (what is to be done, rather than just how something is being done) far better than direct use of language features.
A C++ programmer should know the basics of the standard library, and use it where appropriate.
Any programmer should know the basics of the foundation libraries of the project being worked on, and use them appropriately.
Any programmer using these guidelines should know the [guidelines support library](#gsl-guidelines-support-library), and use it appropriately.
##### Example
change_speed(double s); // bad: what does s signify?
// ...
change_speed(2.3);
A better approach is to be explicit about the meaning of the double (new speed or delta on old speed?) and the unit used:
change_speed(Speed s); // better: the meaning of s is specified
// ...
change_speed(2.3); // error: no unit
change_speed(23_m / 10s); // meters per second
We could have accepted a plain (unit-less) `double` as a delta, but that would have been error-prone.
If we wanted both absolute speed and deltas, we would have defined a `Delta` type.
##### Enforcement
Very hard in general.
* use `const` consistently (check if member functions modify their object; check if functions modify arguments passed by pointer or reference)
* flag uses of casts (casts neuter the type system)
* detect code that mimics the standard library (hard)
### P.2: Write in ISO Standard C++
##### Reason
This is a set of guidelines for writing ISO Standard C++.
##### Note
There are environments where extensions are necessary, e.g., to access system resources.
In such cases, localize the use of necessary extensions and control their use with non-core Coding Guidelines. If possible, build interfaces that encapsulate the extensions so they can be turned off or compiled away on systems that do not support those extensions.
Extensions often do not have rigorously defined semantics. Even extensions that
are common and implemented by multiple compilers might have slightly different
behaviors and edge case behavior as a direct result of *not* having a rigorous
standard definition. With sufficient use of any such extension, expected
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))
and be aware of constructs with implementation defined meaning (e.g., `sizeof(int)`).
##### Note
There are environments where restrictions on use of standard C++ language or library features are necessary, e.g., to avoid dynamic memory allocation as required by aircraft control software standards.
In such cases, control their (dis)use with an extension of these Coding Guidelines customized to the specific environment.
##### Enforcement
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
##### Reason
Unless the intent of some code is stated (e.g., in names or comments), it is impossible to tell whether the code does what it is supposed to do.
##### Example
gsl::index i = 0;
while (i < v.size()) {
// ... do something with v[i] ...
}
The intent of "just" looping over the elements of `v` is not expressed here. The implementation detail of an index is exposed (so that it might be misused), and `i` outlives the scope of the loop, which might or might not be intended. The reader cannot know from just this section of code.
Better:
for (const auto& x : v) { /* do something with the value of x */ }
Now, there is no explicit mention of the iteration mechanism, and the loop operates on a reference to `const` elements so that accidental modification cannot happen. If modification is desired, say so:
for (auto& x : v) { /* modify x */ }
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 */ });
for_each(par, v, [](int x) { /* do something with the value of x */ });
The last variant makes it clear that we are not interested in the order in which the elements of `v` are handled.
A programmer should be familiar with
* [The guidelines support library](#gsl-guidelines-support-library)
* [The ISO C++ Standard Library](#sl-the-standard-library)
* Whatever foundation libraries are used for the current project(s)
##### Note
Alternative formulation: Say what should be done, rather than just how it should be done.
##### Note
Some language constructs express intent better than others.
##### Example
If two `int`s are meant to be the coordinates of a 2D point, say so:
draw_line(int, int, int, int); // obscure: (x1,y1,x2,y2)? (x,y,h,w)? ...?
// need to look up documentation to know
draw_line(Point, Point); // clearer
##### Enforcement
Look for common patterns for which there are better alternatives
* simple `for` loops vs. range-`for` loops
* `f(T*, int)` interfaces vs. `f(span)` interfaces
* loop variables in too large a scope
* naked `new` and `delete`
* functions with many parameters of built-in types
There is a huge scope for cleverness and semi-automated program transformation.
### P.4: Ideally, a program should be statically type safe
##### Reason
Ideally, a program would be completely statically (compile-time) type safe.
Unfortunately, that is not possible. Problem areas:
* unions
* casts
* array decay
* range errors
* narrowing conversions
##### Note
These areas are sources of serious problems (e.g., crashes and security violations).
We try to provide alternative techniques.
##### Enforcement
We can ban, restrain, or detect the individual problem categories separately, as required and feasible for individual programs.
Always suggest an alternative.
For example:
* unions -- use `variant` (in C++17)
* casts -- minimize their use; templates can help
* array decay -- use `span` (from the GSL)
* 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
##### Reason
Code clarity and performance.
You don't need to write error handlers for errors caught at compile time.
##### Example
// Int is an alias used for integers
int bits = 0; // don't: avoidable code
for (Int i = 1; i; i <<= 1)
++bits;
if (bits < 32)
cerr << "Int too small\n";
This example fails to achieve what it is trying to achieve (because overflow is undefined) and should be replaced with a simple `static_assert`:
// Int is an alias used for integers
static_assert(sizeof(Int) >= 4); // do: compile-time check
Or better still just use the type system and replace `Int` with `int32_t`.
##### Example
void read(int* p, int n); // read max n integers into *p
int a[100];
read(a, 1000); // bad, off the end
better
void read(span r); // read into the range of integers r
int a[100];
read(a); // better: let the compiler figure out the number of elements
**Alternative formulation**: Don't postpone to run time what can be done well at compile time.
##### Enforcement
* 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
##### Reason
Leaving hard-to-detect errors in a program is asking for crashes and bad results.
##### Note
Ideally, we catch all errors (that are not errors in the programmer's logic) at either compile time or run time. It is impossible to catch all errors at compile time and often not affordable to catch all remaining errors at run time. However, we should endeavor to write programs that in principle can be checked, given sufficient resources (analysis programs, run-time checks, machine resources, time).
##### Example, bad
// separately compiled, possibly dynamically loaded
extern void f(int* p);
void g(int n)
{
// bad: the number of elements is not passed to f()
f(new int[n]);
}
Here, a crucial bit of information (the number of elements) has been so thoroughly "obscured" that static analysis is probably rendered infeasible and dynamic checking can be very difficult when `f()` is part of an ABI so that we cannot "instrument" that pointer. We could embed helpful information into the free store, but that requires global changes to a system and maybe to the compiler. What we have here is a design that makes error detection very hard.
##### Example, bad
We can of course pass the number of elements along with the pointer:
// separately compiled, possibly dynamically loaded
extern void f2(int* p, int n);
void g2(int n)
{
// bad: the wrong number of elements can be passed to f2()
f2(new int[n], n);
}
Passing the number of elements as an argument is better (and far more common) than just passing the pointer and relying on some (unstated) convention for knowing or discovering the number of elements. However (as shown), a simple typo can introduce a serious error. The connection between the two arguments of `f2()` is conventional, rather than explicit.
Also, it is implicit that `f2()` is supposed to `delete` its argument (or did the caller make a second mistake?).
##### Example, bad
The standard library resource management pointers fail to pass the size when they point to an object:
// separately compiled, possibly dynamically loaded
// NB: this assumes the calling code is ABI-compatible, using a
// compatible C++ compiler and the same stdlib implementation
extern void f3(unique_ptr, int n);
void g3(int n)
{
f3(make_unique(n), m); // bad: pass ownership and size separately
}
##### Example
We need to pass the pointer and the number of elements as an integral object:
extern void f4(vector&); // separately compiled, possibly dynamically loaded
extern void f4(span); // separately compiled, possibly dynamically loaded
// NB: this assumes the calling code is ABI-compatible, using a
// compatible C++ compiler and the same stdlib implementation
void g3(int n)
{
vector v(n);
f4(v); // pass a reference, retain ownership
f4(span{v}); // pass a view, retain ownership
}
This design carries the number of elements along as an integral part of an object, so that errors are unlikely and dynamic (run-time) checking is always feasible, if not always affordable.
##### Example
How do we transfer both ownership and all information needed for validating use?
vector f5(int n) // OK: move
{
vector v(n);
// ... initialize v ...
return v;
}
unique_ptr f6(int n) // bad: loses n
{
auto p = make_unique(n);
// ... initialize *p ...
return p;
}
owner f7(int n) // bad: loses n and we might forget to delete
{
owner p = new int[n];
// ... initialize *p ...
return p;
}
##### Example
* ???
* show how possible checks are avoided by interfaces that pass polymorphic base classes around, when they actually know what they need?
Or strings as "free-style" options
##### Enforcement
* 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
##### Reason
Avoid "mysterious" crashes.
Avoid errors leading to (possibly unrecognized) wrong results.
##### Example
void increment1(int* p, int n) // bad: error-prone
{
for (int i = 0; i < n; ++i) ++p[i];
}
void use1(int m)
{
const int n = 10;
int a[n] = {};
// ...
increment1(a, m); // maybe typo, maybe m <= n is supposed
// but assume that m == 20
// ...
}
Here we made a small error in `use1` that will lead to corrupted data or a crash.
The (pointer, count)-style interface leaves `increment1()` with no realistic way of defending itself against out-of-range errors.
If we could check subscripts for out of range access, then the error would not be discovered until `p[10]` was accessed.
We could check earlier and improve the code:
void increment2(span p)
{
for (int& x : p) ++x;
}
void use2(int m)
{
const int n = 10;
int a[n] = {};
// ...
increment2({a, m}); // maybe typo, maybe m <= n is supposed
// ...
}
Now, `m <= n` can be checked at the point of call (early) rather than later.
If all we had was a typo so that we meant to use `n` as the bound, the code could be further simplified (eliminating the possibility of an error):
void use3(int m)
{
const int n = 10;
int a[n] = {};
// ...
increment2(a); // the number of elements of a need not be repeated
// ...
}
##### Example, bad
Don't repeatedly check the same value. Don't pass structured data as strings:
Date read_date(istream& is); // read date from istream
Date extract_date(const string& s); // extract date from string
void user1(const string& date) // manipulate date
{
auto d = extract_date(date);
// ...
}
void user2()
{
Date d = read_date(cin);
// ...
user1(d.to_string());
// ...
}
The date is validated twice (by the `Date` constructor) and passed as a character string (unstructured data).
##### Example
Excess checking can be costly.
There are cases where checking early is inefficient because you might never need the value, or might only need part of the value that is more easily checked than the whole. Similarly, don't add validity checks that change the asymptotic behavior of your interface (e.g., don't add a `O(n)` check to an interface with an average complexity of `O(1)`).
class Jet { // Physics says: e * e < x * x + y * y + z * z
float x;
float y;
float z;
float e;
public:
Jet(float x, float y, float z, float e)
:x(x), y(y), z(z), e(e)
{
// Should I check here that the values are physically meaningful?
}
float m() const
{
// Should I handle the degenerate case here?
return sqrt(x * x + y * y + z * z - e * e);
}
???
};
The physical law for a jet (`e * e < x * x + y * y + z * z`) is not an invariant because of the possibility for measurement errors.
???
##### Enforcement
* Look at pointers and arrays: Do range-checking early and not repeatedly
* Look at conversions: Eliminate or mark narrowing conversions
* Look for unchecked values coming from input
* Look for structured data (objects of classes with invariants) being converted into strings
* ???
### P.8: Don't leak any resources
##### Reason
Even a slow growth in resources will, over time, exhaust the availability of those resources.
This is particularly important for long-running programs, but is an essential piece of responsible programming behavior.
##### Example, bad
void f(const char* name)
{
FILE* input = fopen(name, "r");
// ...
if (something) return; // bad: if something == true, a file handle is leaked
// ...
fclose(input);
}
Prefer [RAII](#rr-raii):
void f(const char* name)
{
ifstream input {name};
// ...
if (something) return; // OK: no leak
// ...
}
**See also**: [The resource management section](#s-resource)
##### Note
A leak is colloquially "anything that isn't cleaned up."
The more important classification is "anything that can no longer be cleaned up."
For example, allocating an object on the heap and then losing the last pointer that points to that allocation.
This rule should not be taken as requiring that allocations within long-lived objects must be returned during program shutdown.
For example, relying on system guaranteed cleanup such as file closing and memory deallocation upon process shutdown can simplify code.
However, relying on abstractions that implicitly clean up can be as simple, and often safer.
##### 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.
##### Enforcement
* Look at pointers: Classify them into non-owners (the default) and owners.
Where feasible, replace owners with standard-library resource handles (as in the example above).
Alternatively, mark an owner as such using `owner` from [the GSL](#gsl-guidelines-support-library).
* 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
##### Reason
This is C++.
##### Note
Time and space that you spend well to achieve a goal (e.g., speed of development, resource safety, or simplification of testing) is not wasted.
"Another benefit of striving for efficiency is that the process forces you to understand the problem in more depth." - Alex Stepanov
##### Example, bad
struct X {
char ch;
int i;
string s;
char ch2;
X& operator=(const X& a);
X(const X&);
};
X waste(const char* p)
{
if (!p) throw Nullptr_error{};
int n = strlen(p);
auto buf = new char[n];
if (!buf) throw Allocation_error{};
for (int i = 0; i < n; ++i) buf[i] = p[i];
// ... manipulate buffer ...
X x;
x.ch = 'a';
x.s = string(n); // give x.s space for *p
for (gsl::index i = 0; i < x.s.size(); ++i) x.s[i] = buf[i]; // copy buf into x.s
delete[] buf;
return x;
}
void driver()
{
X x = waste("Typical argument");
// ...
}
Yes, this is a caricature, but we have seen every individual mistake in production code, and worse.
Note that the layout of `X` guarantees that at least 6 bytes (and most likely more) are wasted.
The spurious definition of copy operations disables move semantics so that the return operation is slow
(please note that the Return Value Optimization, RVO, is not guaranteed here).
The use of `new` and `delete` for `buf` is redundant; if we really needed a local string, we should use a local `string`.
There are several more performance bugs and gratuitous complication.
##### Example, bad
void lower(zstring s)
{
for (int i = 0; i < strlen(s); ++i) s[i] = tolower(s[i]);
}
This is actually an example from production code.
We can see that in our condition we have `i < strlen(s)`. This expression will be evaluated on every iteration of the loop, which means that `strlen` must walk through string every loop to discover its length. While the string contents are changing, it's assumed that `tolower` will not affect the length of the string, so it's better to cache the length outside the loop and not incur that cost each iteration.
##### Note
An individual example of waste is rarely significant, and where it is significant, it is typically easily eliminated by an expert.
However, waste spread liberally across a code base can easily be significant and experts are not always as available as we would like.
The aim of this rule (and the more specific rules that support it) is to eliminate most waste related to the use of C++ before it happens.
After that, we can look at waste related to algorithms and requirements, but that is beyond the scope of these guidelines.
##### Enforcement
Many more specific rules aim at the overall goals of simplicity and elimination of gratuitous waste.
* 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
##### Reason
It is easier to reason about constants than about variables.
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)
### P.11: Encapsulate messy constructs, rather than spreading through the code
##### Reason
Messy code is more likely to hide bugs and harder to write.
A good interface is easier and safer to use.
Messy, low-level code breeds more such code.
##### Example
int sz = 100;
int* p = (int*) malloc(sizeof(int) * sz);
int count = 0;
// ...
for (;;) {
// ... read an int into x, exit loop if end of file is reached ...
// ... check that x is valid ...
if (count == sz)
p = (int*) realloc(p, sizeof(int) * sz * 2);
p[count++] = x;
// ...
}
This is low-level, verbose, and error-prone.
For example, we "forgot" to test for memory exhaustion and assign new value to `sz`.
Instead, we could use `vector`:
vector v;
v.reserve(100);
// ...
for (int x; cin >> x; ) {
// ... check that x is valid ...
v.push_back(x);
}
##### Note
The standards library and the GSL are examples of this philosophy.
For example, instead of messing with the arrays, unions, cast, tricky lifetime issues, `gsl::owner`, etc.,
that are needed to implement key abstractions, such as `vector`, `span`, `lock_guard`, and `future`, we use the libraries
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.
##### Enforcement
* Look for "messy code" such as complex pointer manipulation and casting outside the implementation of abstractions.
### P.12: Use supporting tools as appropriate
##### Reason
There are many things that are done better "by machine".
Computers don't tire or get bored by repetitive tasks.
We typically have better things to do than repeatedly do routine tasks.
##### Example
Run a static analyzer to verify that your code follows the guidelines you want it to follow.
##### Note
See
* [Static analysis tools](https://en.wikipedia.org/wiki/List_of_tools_for_static_code_analysis)
* [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.,
but those are beyond the scope of these guidelines.
##### Note
Be careful not to become dependent on over-elaborate or over-specialized tool chains.
Those can make your otherwise portable code non-portable.
### P.13: Use support libraries as appropriate
##### Reason
Using a well-designed, well-documented, and well-supported library saves time and effort;
its quality and documentation are likely to be greater than what you could do
if the majority of your time must be spent on an implementation.
The cost (time, effort, money, etc.) of a library can be shared over many users.
A widely used library is more likely to be kept up-to-date and ported to new systems than an individual application.
Knowledge of a widely-used library can save time on other/future projects.
So, if a suitable library exists for your application domain, use it.
##### Example
std::sort(begin(v), end(v), std::greater<>());
Unless you are an expert in sorting algorithms and have plenty of time,
this is more likely to be correct and to run faster than anything you write for a specific application.
You need a reason not to use the standard library (or whatever foundational libraries your application uses) rather than a reason to use it.
##### Note
By default use
* The [ISO C++ Standard Library](#sl-the-standard-library)
* The [Guidelines Support Library](#gsl-guidelines-support-library)
##### Note
If no well-designed, well-documented, and well-supported library exists for an important domain,
maybe you should design and implement it, and then use it.
# 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)
**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)
### I.1: Make interfaces explicit
##### Reason
Correctness. Assumptions not stated in an interface are easily overlooked and hard to test.
##### Example, bad
Controlling the behavior of a function through a global (namespace scope) variable (a call mode) is implicit and potentially confusing. For example:
int round(double d)
{
return (round_up) ? ceil(d) : d; // don't: "invisible" dependency
}
It will not be obvious to a caller that the meaning of two calls of `round(7.2)` might give different results.
##### Exception
Sometimes we control the details of a set of operations by an environment variable, e.g., normal vs. verbose output or debug vs. optimized.
The use of a non-local control is potentially confusing, but controls only implementation details of otherwise fixed semantics.
##### Example, bad
Reporting through non-local variables (e.g., `errno`) is easily ignored. For example:
// don't: no test of fprintf's return value
fprintf(connection, "logging: %d %d %d\n", x, y, s);
What if the connection goes down so that no logging output is produced? See I.???.
**Alternative**: Throw an exception. An exception cannot be ignored.
**Alternative formulation**: Avoid passing information across an interface through non-local or implicit state.
Note that non-`const` member functions pass information to other member functions through their object's state.
**Alternative formulation**: An interface should be a function or a set of functions.
Functions can be function templates and sets of functions can be classes or class templates.
##### Enforcement
* (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
##### Reason
Non-`const` global variables hide dependencies and make the dependencies subject to unpredictable changes.
##### Example
struct Data {
// ... lots of stuff ...
} data; // non-const data
void compute() // don't
{
// ... use data ...
}
void output() // don't
{
// ... use data ...
}
Who else might modify `data`?
**Warning**: The initialization of global objects is not totally ordered.
If you use a global object initialize it with a constant.
Note that it is possible to get undefined initialization order even for `const` objects.
##### Exception
A global object is often better than a singleton.
##### Note
Global constants are useful.
##### Note
The rule against global variables applies to namespace scope variables as well.
**Alternative**: If you use global (more generally namespace scope) data to avoid copying, consider passing the data as an object by reference to `const`.
Another solution is to define the data as the state of some object and the operations as member functions.
**Warning**: Beware of data races: If one thread can access non-local data (or data passed by reference) while another thread executes the callee, we can have a data race.
Every pointer or reference to mutable data is a potential data race.
Using global pointers or references to access and change non-const, and otherwise non-global,
data isn't a better alternative to non-const global variables since that doesn't solve the issues of hidden dependencies or potential race conditions.
##### Note
You cannot have a race condition on immutable data.
**References**: See the [rules for calling functions](#ss-call).
##### Note
The rule is "avoid", not "don't use." Of course there will be (rare) exceptions, such as `cin`, `cout`, and `cerr`.
##### Enforcement
(Simple) Report all non-`const` variables declared at namespace scope and global pointers/references to non-const data.
### I.3: Avoid singletons
##### Reason
Singletons are basically complicated global objects in disguise.
##### Example
class Singleton {
// ... lots of stuff to ensure that only one Singleton object is created,
// that it is initialized properly, etc.
};
There are many variants of the singleton idea.
That's part of the problem.
##### Note
If you don't want a global object to change, declare it `const` or `constexpr`.
##### Exception
You can use the simplest "singleton" (so simple that it is often not considered a singleton) to get initialization on first use, if any:
X& myX()
{
static X my_x {3};
return my_x;
}
This is one of the most effective solutions to problems related to initialization order.
In a multi-threaded environment, the initialization of the static object does not introduce a race condition
(unless you carelessly access a shared object from within its constructor).
Note that the initialization of a local `static` does not imply a race condition.
However, if the destruction of `X` involves an operation that needs to be synchronized we must use a less simple solution.
For example:
X& myX()
{
static auto p = new X {3};
return *p; // potential leak
}
Now someone must `delete` that object in some suitably thread-safe way.
That's error-prone, so we don't use that technique unless
* `myX` is in multi-threaded code,
* that `X` object needs to be destroyed (e.g., because it releases a resource), and
* `X`'s destructor's code needs to be synchronized.
If you, as many do, define a singleton as a class for which only one object is created, functions like `myX` are not singletons, and this useful technique is not an exception to the no-singleton rule.
##### Enforcement
Very hard in general.
* Look for classes with names that include `singleton`.
* 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
##### Reason
Types are the simplest and best documentation, improve legibility due to their well-defined meaning, and are checked at compile time.
Also, precisely typed code is often optimized better.
##### Example, don't
Consider:
void pass(void* data); // weak and under-qualified type void* is suspicious
Callers are unsure what types are allowed and if the data may
be mutated as `const` is not specified. Note all pointer types
implicitly convert to `void*`, so it is easy for callers to provide this value.
The callee must `static_cast` data to an unverified type to use it.
That is error-prone and verbose.
Only use `const void*` for passing in data in designs that are indescribable in C++. Consider using a `variant` or a pointer to base instead.
**Alternative**: Often, a template parameter can eliminate the `void*` turning it into a `T*` or `T&`.
For generic code these `T`s can be general or concept constrained template parameters.
##### Example, bad
Consider:
draw_rect(100, 200, 100, 500); // what do the numbers specify?
draw_rect(p.x, p.y, 10, 20); // what units are 10 and 20 in?
It is clear that the caller is describing a rectangle, but it is unclear what parts they relate to. Also, an `int` can carry arbitrary forms of information, including values of many units, so we must guess about the meaning of the four `int`s. Most likely, the first two are an `x`,`y` coordinate pair, but what are the last two?
Comments and parameter names can help, but we could be explicit:
void draw_rectangle(Point top_left, Point bottom_right);
void draw_rectangle(Point top_left, Size height_width);
draw_rectangle(p, Point{10, 20}); // two corners
draw_rectangle(p, Size{10, 20}); // one corner and a (height, width) pair
Obviously, we cannot catch all errors through the static type system
(e.g., the fact that a first argument is supposed to be a top-left point is left to convention (naming and comments)).
##### Example, bad
Consider:
set_settings(true, false, 42); // what do the numbers specify?
The parameter types and their values do not communicate what settings are being specified or what those values mean.
This design is more explicit, safe and legible:
alarm_settings s{};
s.enabled = true;
s.displayMode = alarm_settings::mode::spinning_light;
s.frequency = alarm_settings::every_10_seconds;
set_settings(s);
For the case of a set of boolean values consider using a flags `enum`; a pattern that expresses a set of boolean values.
enable_lamp_options(lamp_option::on | lamp_option::animate_state_transitions);
##### Example, bad
In the following example, it is not clear from the interface what `time_to_blink` means: Seconds? Milliseconds?
void blink_led(int time_to_blink) // bad -- the unit is ambiguous
{
// ...
// do something with time_to_blink
// ...
}
void use()
{
blink_led(2);
}
##### Example, good
`std::chrono::duration` types help making the unit of time duration explicit.
void blink_led(milliseconds time_to_blink) // good -- the unit is explicit
{
// ...
// do something with time_to_blink
// ...
}
void use()
{
blink_led(1500ms);
}
The function can also be written in such a way that it will accept any time duration unit.
template
void blink_led(duration time_to_blink) // good -- accepts any unit
{
// assuming that millisecond is the smallest relevant unit
auto milliseconds_to_blink = duration_cast(time_to_blink);
// ...
// do something with milliseconds_to_blink
// ...
}
void use()
{
blink_led(2s);
blink_led(1500ms);
}
##### Enforcement
* (Simple) Report the use of `void*` as a parameter or return type.
* (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)
##### Reason
Arguments have meaning that might constrain their proper use in the callee.
##### Example
Consider:
double sqrt(double x);
Here `x` must be non-negative. The type system cannot (easily and naturally) express that, so we must use other means. For example:
double sqrt(double x); // x must be non-negative
Some preconditions can be expressed as assertions. For example:
double sqrt(double x) { Expects(x >= 0); /* ... */ }
Ideally, that `Expects(x >= 0)` should be part of the interface of `sqrt()` but that's not easily done. For now, we place it in the definition (function body).
**References**: `Expects()` is described in [GSL](#gsl-guidelines-support-library).
##### Note
Prefer a formal specification of requirements, such as `Expects(p);`.
If that is infeasible, use English text in comments, such as `// the sequence [p:q) is ordered using <`.
##### Note
Most member functions have as a precondition that some class invariant holds.
That invariant is established by a constructor and must be reestablished upon exit by every member function called from outside the class.
We don't need to mention it for each member function.
##### Enforcement
(Not enforceable)
**See also**: The rules for passing pointers. ???
### I.6: Prefer `Expects()` for expressing preconditions
##### Reason
To make it clear that the condition is a precondition and to enable tool use.
##### Example
int area(int height, int width)
{
Expects(height > 0 && width > 0); // good
if (height <= 0 || width <= 0) my_error(); // obscure
// ...
}
##### Note
Preconditions 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 (do you always want to abort in debug mode and check nothing in productions runs?).
##### Note
Preconditions should be part of the interface rather than part of the implementation,
but we don't yet have the language facilities to do that.
Once language support becomes available (e.g., see the [contract proposal](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0380r1.pdf)) we will adopt the standard version of preconditions, postconditions, and assertions.
##### Note
`Expects()` can also be used to check a condition in the middle of an algorithm.
##### Note
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
##### Reason
To detect misunderstandings about the result and possibly catch erroneous implementations.
##### Example, bad
Consider:
int area(int height, int width) { return height * width; } // bad
Here, we (incautiously) left out the precondition specification, so it is not explicit that height and width must be positive.
We also left out the postcondition specification, so it is not obvious that the algorithm (`height * width`) is wrong for areas larger than the largest integer.
Overflow can happen.
Consider using:
int area(int height, int width)
{
auto res = height * width;
Ensures(res > 0);
return res;
}
##### Example, bad
Consider a famous security bug:
void f() // problematic
{
char buffer[MAX];
// ...
memset(buffer, 0, sizeof(buffer));
}
There was no postcondition stating that the buffer should be cleared and the optimizer eliminated the apparently redundant `memset()` call:
void f() // better
{
char buffer[MAX];
// ...
memset(buffer, 0, sizeof(buffer));
Ensures(buffer[0] == 0);
}
##### Note
Postconditions are often informally stated in a comment that states the purpose of a function; `Ensures()` can be used to make this more systematic, visible, and checkable.
##### Note
Postconditions are especially important when they relate to something that is not directly reflected in a returned result, such as a state of a data structure used.
##### Example
Consider a function that manipulates a `Record`, using a `mutex` to avoid race conditions:
mutex m;
void manipulate(Record& r) // don't
{
m.lock();
// ... no m.unlock() ...
}
Here, we "forgot" to state that the `mutex` should be released, so we don't know if the failure to ensure release of the `mutex` was a bug or a feature.
Stating the postcondition would have made it clear:
void manipulate(Record& r) // postcondition: m is unlocked upon exit
{
m.lock();
// ... no m.unlock() ...
}
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:
void manipulate(Record& r) // best
{
lock_guard _ {m};
// ...
}
##### Note
Ideally, postconditions are stated in the interface/declaration so that users can easily see them.
Only postconditions related to the users can be stated in the interface.
Postconditions related only to internal state belong in the definition/implementation.
##### Enforcement
(Not enforceable) This is a philosophical guideline that is infeasible to check
directly in the general case. Domain specific checkers (like lock-holding
checkers) exist for many toolchains.
### I.8: Prefer `Ensures()` for expressing postconditions
##### Reason
To make it clear that the condition is a postcondition and to enable tool use.
##### Example
void f()
{
char buffer[MAX];
// ...
memset(buffer, 0, MAX);
Ensures(buffer[0] == 0);
}
##### Note
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).
##### Note
Ideally, that `Ensures` should be part of the interface, but that's not easily done.
For now, we place it in the definition (function body).
Once language support becomes available (e.g., see the [contract proposal](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0380r1.pdf)) we will adopt the standard version of preconditions, postconditions, and assertions.
##### Enforcement
(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
##### Reason
Make the interface precisely specified and compile-time checkable in the (not so distant) future.
##### Example
Use the C++20 style of requirements specification. For example:
template
requires input_iterator && equality_comparable_with, Val>
Iter find(Iter first, Iter last, Val v)
{
// ...
}
**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
##### Reason
It should not be possible to ignore an error because that could leave the system or a computation in an undefined (or unexpected) state.
This is a major source of errors.
##### Example
int printf(const char* ...); // bad: return negative number if output fails
template
// good: throw system_error if unable to start the new thread
explicit thread(F&& f, Args&&... args);
##### Note
What is an error?
An error means that the function cannot achieve its advertised purpose (including establishing postconditions).
Calling code that ignores an error could lead to wrong results or undefined systems state.
For example, not being able to connect to a remote server is not by itself an error:
the server can refuse a connection for all kinds of reasons, so the natural thing is to return a result that the caller should always check.
However, if failing to make a connection is considered an error, then a failure should throw an exception.
##### Exception
Many traditional interface functions (e.g., UNIX signal handlers) use error codes (e.g., `errno`) to report what are really status codes, rather than errors. You don't have a good alternative to using such, so calling these does not violate the rule.
##### Alternative
If you can't use exceptions (e.g., because your code is full of old-style raw-pointer use or because there are hard-real-time constraints), consider using a style that returns a pair of values:
int val;
int error_code;
tie(val, error_code) = do_something();
if (error_code) {
// ... handle the error or exit ...
}
// ... use val ...
This style unfortunately leads to uninitialized variables.
Since C++17 the "structured bindings" feature can be used to initialize variables directly from the return value:
auto [val, error_code] = do_something();
if (error_code) {
// ... handle the error or exit ...
}
// ... use val ...
##### Note
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.
* In the longer term, more regular code gets better optimized.
* 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.
##### 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&`)
##### Reason
If there is any doubt whether the caller or the callee owns an object, leaks or premature destruction will occur.
##### Example
Consider:
X* compute(args) // don't
{
X* res = new X{};
// ...
return res;
}
Who deletes the returned `X`? The problem would be harder to spot if `compute` returned a reference.
Consider returning the result by value (use move semantics if the result is large):
vector compute(args) // good
{
vector res(10000);
// ...
return res;
}
**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.
**Alternative**: Sometimes older code can't be modified because of ABI compatibility requirements or lack of resources.
In that case, mark owning pointers using `owner` from the [guidelines support library](#gsl-guidelines-support-library):
owner compute(args) // It is now clear that ownership is transferred
{
owner res = new X{};
// ...
return res;
}
This tells analysis tools that `res` is an owner.
That is, its value must be `delete`d or transferred to another owner, as is done here by the `return`.
`owner` is used similarly in the implementation of resource handles.
##### Note
Every object passed as a raw pointer (or iterator) is assumed to be owned by the
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).
##### Enforcement
* (Simple) Warn on `delete` of a raw pointer that is not an `owner`. Suggest use of standard-library resource handle or use of `owner`.
* (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`
##### Reason
To help avoid dereferencing `nullptr` errors.
To improve performance by avoiding redundant checks for `nullptr`.
##### Example
int length(const char* p); // it is not clear whether length(nullptr) is valid
length(nullptr); // OK?
int length(not_null p); // better: we can assume that p cannot be nullptr
int length(const char* p); // we must assume that p can be nullptr
By stating the intent in source, implementers and tools can provide better diagnostics, such as finding some classes of errors through static analysis, and perform optimizations, such as removing branches and null tests.
##### Note
`not_null` is defined in the [guidelines support library](#gsl-guidelines-support-library).
##### Note
The assumption that the pointer to `char` pointed to a C-style string (a zero-terminated string of characters) was still implicit, and a potential source of confusion and errors. Use `czstring` in preference to `const char*`.
// we can assume that p cannot be nullptr
// we can assume that p points to a zero-terminated array of characters
int length(not_null p);
Note: `length()` is, of course, `std::strlen()` in disguise.
##### Enforcement
* (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
##### Reason
(pointer, size)-style interfaces are error-prone. Also, a plain pointer (to array) must rely on some convention to allow the callee to determine the size.
##### Example
Consider:
void copy_n(const T* p, T* q, int n); // copy from [p:p+n) to [q:q+n)
What if there are fewer than `n` elements in the array pointed to by `q`? Then, we overwrite some probably unrelated memory.
What if there are fewer than `n` elements in the array pointed to by `p`? Then, we read some probably unrelated memory.
Either is undefined behavior and a potentially very nasty bug.
##### Alternative
Consider using explicit spans:
void copy(span r, span r2); // copy r to r2
##### Example, bad
Consider:
void draw(Shape* p, int n); // poor interface; poor code
Circle arr[10];
// ...
draw(arr, 10);
Passing `10` as the `n` argument might be a mistake: the most common convention is to assume `[0:n)` but that is nowhere stated. Worse is that the call of `draw()` compiled at all: there was an implicit conversion from array to pointer (array decay) and then another implicit conversion from `Circle` to `Shape`. There is no way that `draw()` can safely iterate through that array: it has no way of knowing the size of the elements.
**Alternative**: Use a support class that ensures that the number of elements is correct and prevents dangerous implicit conversions. For example:
void draw2(span);
Circle arr[10];
// ...
draw2(span(arr)); // deduce the number of elements
draw2(arr); // deduce the element type and array size
void draw3(span);
draw3(arr); // error: cannot convert Circle[10] to span
This `draw2()` passes the same amount of information to `draw()`, but makes the fact that it is supposed to be a range of `Circle`s explicit. See ???.
##### Exception
Use `zstring` and `czstring` to represent C-style, zero-terminated strings.
But when doing so, use `std::string_view` or `span` from the [GSL](#gsl-guidelines-support-library) to prevent range errors.
##### Enforcement
* (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
##### Reason
Complex initialization can lead to undefined order of execution.
##### Example
// file1.c
extern const X x;
const Y y = f(x); // read x; write y
// file2.c
extern const Y y;
const X x = g(y); // read y; write x
Since `x` and `y` are in different translation units the order of calls to `f()` and `g()` is undefined;
one will access an uninitialized `const`.
This shows that the order-of-initialization problem for global (namespace scope) objects is not limited to global *variables*.
##### Note
Order of initialization problems become particularly difficult to handle in concurrent code.
It is usually best to avoid global (namespace scope) objects altogether.
##### Enforcement
* 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
##### Reason
Having many arguments opens opportunities for confusion. Passing lots of arguments is often costly compared to alternatives.
##### Discussion
The two most common reasons why functions have too many parameters are:
1. *Missing an abstraction.*
There is an abstraction missing, so that a compound value is being
passed as individual elements instead of as a single object that enforces an invariant.
This not only expands the parameter list, but it leads to errors because the component values
are no longer protected by an enforced invariant.
2. *Violating "one function, one responsibility."*
The function is trying to do more than one job and should probably be refactored.
##### Example
The standard-library `merge()` is at the limit of what we can comfortably handle:
template
OutputIterator merge(InputIterator1 first1, InputIterator1 last1,
InputIterator2 first2, InputIterator2 last2,
OutputIterator result, Compare comp);
Note that this is because of problem 1 above -- missing abstraction. Instead of passing a range (abstraction), STL passed iterator pairs (unencapsulated component values).
Here, we have four template arguments and six function arguments.
To simplify the most frequent and simplest uses, the comparison argument can be defaulted to `<`:
template
OutputIterator merge(InputIterator1 first1, InputIterator1 last1,
InputIterator2 first2, InputIterator2 last2,
OutputIterator result);
This doesn't reduce the total complexity, but it reduces the surface complexity presented to many users.
To really reduce the number of arguments, we need to bundle the arguments into higher-level abstractions:
template
OutputIterator merge(InputRange1 r1, InputRange2 r2, OutputIterator result);
Grouping arguments into "bundles" is a general technique to reduce the number of arguments and to increase the opportunities for checking.
Alternatively, we could use a standard library concept to define the notion of three types that must be usable for merging:
template
requires mergeable
Out merge(In1 r1, In2 r2, Out result);
##### Example
The safety Profiles recommend replacing
void f(int* some_ints, int some_ints_length); // BAD: C style, unsafe
with
void f(gsl::span some_ints); // GOOD: safe, bounds-checked
Here, using an abstraction has safety and robustness benefits, and naturally also reduces the number of parameters.
##### Note
How many parameters are too many? Try to use fewer than four (4) parameters.
There are functions that are best expressed with four individual parameters, but not many.
**Alternative**: Use better abstraction: Group arguments into meaningful objects and pass the objects (by value or by reference).
**Alternative**: Use default arguments or overloads to allow the most common forms of calls to be done with fewer arguments.
##### Enforcement
* 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
##### Reason
Adjacent arguments of the same type are easily swapped by mistake.
##### Example, bad
Consider:
void copy_n(T* p, T* q, int n); // copy from [p:p + n) to [q:q + n)
This is a nasty variant of a K&R C-style interface. It is easy to reverse the "to" and "from" arguments.
Use `const` for the "from" argument:
void copy_n(const T* p, T* q, int n); // copy from [p:p + n) to [q:q + n)
##### Exception
If the order of the parameters is not important, there is no problem:
int max(int a, int b);
##### Alternative
Don't pass arrays as pointers, pass an object representing a range (e.g., a `span`):
void copy_n(span p, span q); // copy from p to q
##### Alternative
Define a `struct` as the parameter type and name the fields for those parameters accordingly:
struct SystemParams {
string config_file;
string output_path;
seconds timeout;
};
void initialize(SystemParams p);
This tends to make invocations of this clear to future readers, as the parameters
are often filled in by name at the call site.
##### Note
Only the interface's designer can adequately address the source of violations of this guideline.
##### Enforcement strategy
(Simple) Warn if two consecutive parameters share the same type.
We are still looking for a less-simple enforcement.
### I.25: Prefer empty abstract classes as interfaces to class hierarchies
##### Reason
Abstract classes that are empty (have no non-static member data) are more likely to be stable than base classes with state.
##### Example, bad
You just knew that `Shape` would turn up somewhere :-)
class Shape { // bad: interface class loaded with data
public:
Point center() const { return c; }
virtual void draw() const;
virtual void rotate(int);
// ...
private:
Point c;
vector outline;
Color col;
};
This will force every derived class to compute a center -- even if that's non-trivial and the center is never used. Similarly, not every `Shape` has a `Color`, and many `Shape`s are best represented without an outline defined as a sequence of `Point`s. Using an abstract class is better:
class Shape { // better: Shape is a pure interface
public:
virtual Point center() const = 0; // pure virtual functions
virtual void draw() const = 0;
virtual void rotate(int) = 0;
// ...
// ... no data members ...
// ...
virtual ~Shape() = default;
};
##### Enforcement
(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
##### Reason
Different compilers implement different binary layouts for classes, exception handling, function names, and other implementation details.
##### Exception
Common ABIs are emerging on some platforms freeing you from the more draconian restrictions.
##### Note
If you use a single compiler, you can use full C++ in interfaces. That might require recompilation after an upgrade to a new compiler version.
##### Enforcement
(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
##### Reason
Because private data members participate in class layout and private member functions participate in overload resolution, changes to those
implementation details require recompilation of all users of a class that uses them. A non-polymorphic interface class holding a pointer to
implementation (Pimpl) can isolate the users of a class from changes in its implementation at the cost of an indirection.
##### Example
interface (widget.h)
class widget {
class impl;
std::unique_ptr pimpl;
public:
void draw(); // public API that will be forwarded to the implementation
widget(int); // defined in the implementation file
~widget(); // defined in the implementation file, where impl is a complete type
widget(widget&&) noexcept; // defined in the implementation file
widget(const widget&) = delete;
widget& operator=(widget&&) noexcept; // defined in the implementation file
widget& operator=(const widget&) = delete;
};
implementation (widget.cpp)
class widget::impl {
int n; // private data
public:
void draw(const widget& w) { /* ... */ }
impl(int n) : n(n) {}
};
void widget::draw() { pimpl->draw(*this); }
widget::widget(int n) : pimpl{std::make_unique(n)} {}
widget::widget(widget&&) noexcept = default;
widget::~widget() = default;
widget& widget::operator=(widget&&) noexcept = default;
##### Notes
See [GOTW #100](https://herbsutter.com/gotw/_100/) and [cppreference](https://en.cppreference.com/w/cpp/language/pimpl) for the trade-offs and additional implementation details associated with this idiom.
##### Enforcement
(Not enforceable) It is difficult to reliably identify where an interface forms part of an ABI.
### I.30: Encapsulate rule violations
##### Reason
To keep code simple and safe.
Sometimes, ugly, unsafe, or error-prone techniques are necessary for logical or performance reasons.
If so, keep them local, rather than "infecting" interfaces so that larger groups of programmers have to be aware of the
subtleties.
Implementation complexity should, if at all possible, not leak through interfaces into user code.
##### Example
Consider a program that, depending on some form of input (e.g., arguments to `main`), should consume input
from a file, from the command line, or from standard input.
We might write
bool owned;
owner inp;
switch (source) {
case std_in: owned = false; inp = &cin; break;
case command_line: owned = true; inp = new istringstream{argv[2]}; break;
case file: owned = true; inp = new ifstream{argv[2]}; break;
}
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).
In particular, someone has to remember to somewhere write
if (owned) delete inp;
We could handle this particular example by using `unique_ptr` with a special deleter that does nothing for `cin`,
but that's complicated for novices (who can easily encounter this problem) and the example is an example of a more general
problem where a property that we would like to consider static (here, ownership) needs infrequently be addressed
at run time.
The common, most frequent, and safest examples can be handled statically, so we don't want to add cost and complexity to those.
But we must also cope with the uncommon, less-safe, and necessarily more expensive cases.
Such examples are discussed in [[Str15]](https://www.stroustrup.com/resource-model.pdf).
So, we write a class
class Istream { [[gsl::suppress("lifetime")]]
public:
enum Opt { from_line = 1 };
Istream() { }
Istream(czstring p) : owned{true}, inp{new ifstream{p}} {} // read from file
Istream(czstring p, Opt) : owned{true}, inp{new istringstream{p}} {} // read from command line
~Istream() { if (owned) delete inp; }
operator istream&() { return *inp; }
private:
bool owned = false;
istream* inp = &cin;
};
Now, the dynamic nature of `istream` ownership has been encapsulated.
Presumably, a bit of checking for potential errors would be added in real code.
##### Enforcement
* Hard, it is hard to decide what rule-breaking code is essential
* Flag rule suppression that enable rule-violations to cross interfaces
# 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.
It should be possible to name a function meaningfully, to specify the requirements of its argument, and clearly state the relationship between the arguments and the result. An implementation is not a specification. Try to think about what a function does as well as about how it does it.
Functions are the most critical part in most interfaces, so see the interface rules.
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)
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)
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)
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)
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)
Functions have strong similarities to lambdas and function objects.
**See also**: [C.lambdas: Function objects and lambdas](#ss-lambdas)
## 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
##### Reason
Factoring out common code makes code more readable, more likely to be reused, and limit errors from complex code.
If something is a well-specified action, separate it out from its surrounding code and give it a name.
##### Example, don't
void read_and_print(istream& is) // read and print an int
{
int x;
if (is >> x)
cout << "the int is " << x << '\n';
else
cerr << "no int on input\n";
}
Almost everything is wrong with `read_and_print`.
It reads, it writes (to a fixed `ostream`), it writes error messages (to a fixed `ostream`), it handles only `int`s.
There is nothing to reuse, logically separate operations are intermingled and local variables are in scope after the end of their logical use.
For a tiny example, this looks OK, but if the input operation, the output operation, and the error handling had been more complicated the tangled
mess could become hard to understand.
##### Note
If you write a non-trivial lambda that potentially can be used in more than one place, give it a name by assigning it to a (usually non-local) variable.
##### Example
sort(a, b, [](T x, T y) { return x.rank() < y.rank() && x.value() < y.value(); });
Naming that lambda breaks up the expression into its logical parts and provides a strong hint to the meaning of the lambda.
auto lessT = [](T x, T y) { return x.rank() < y.rank() && x.value() < y.value(); };
sort(a, b, lessT);
The shortest code is not always the best for performance or maintainability.
##### Exception
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."
Similarly, lambdas used as callback arguments are sometimes non-trivial, yet unlikely to be reusable.
##### Enforcement
* 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
##### Reason
A function that performs a single operation is simpler to understand, test, and reuse.
##### Example
Consider:
void read_and_print() // bad
{
int x;
cin >> x;
// check for errors
cout << x << "\n";
}
This is a monolith that is tied to a specific input and will never find another (different) use. Instead, break functions up into suitable logical parts and parameterize:
int read(istream& is) // better
{
int x;
is >> x;
// check for errors
return x;
}
void print(ostream& os, int x)
{
os << x << "\n";
}
These can now be combined where needed:
void read_and_print()
{
auto x = read(cin);
print(cout, x);
}
If there was a need, we could further templatize `read()` and `print()` on the data type, the I/O mechanism, the response to errors, etc. Example:
auto read = [](auto& input, auto& value) // better
{
input >> value;
// check for errors
};
void print(auto& output, const auto& value)
{
output << value << "\n";
}
##### Enforcement
* Consider functions with more than one "out" parameter suspicious. Use return values instead, including `tuple` for multiple return values.
* 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
##### Reason
Large functions are hard to read, more likely to contain complex code, and more likely to have variables in larger than minimal scopes.
Functions with complex control structures are more likely to be long and more likely to hide logical errors
##### Example
Consider:
double simple_func(double val, int flag1, int flag2)
// simple_func: takes a value and calculates the expected ASIC output,
// given the two mode flags.
{
double intermediate;
if (flag1 > 0) {
intermediate = func1(val);
if (flag2 % 2)
intermediate = sqrt(intermediate);
}
else if (flag1 == -1) {
intermediate = func1(-val);
if (flag2 % 2)
intermediate = sqrt(-intermediate);
flag1 = -flag1;
}
if (abs(flag2) > 10) {
intermediate = func2(intermediate);
}
switch (flag2 / 10) {
case 1: if (flag1 == -1) return finalize(intermediate, 1.171);
break;
case 2: return finalize(intermediate, 13.1);
default: break;
}
return finalize(intermediate, 0.);
}
This is too complex.
How would you know if all possible alternatives have been correctly handled?
Yes, it breaks other rules also.
We can refactor:
double func1_muon(double val, int flag)
{
// ???
}
double func1_tau(double val, int flag1, int flag2)
{
// ???
}
double simple_func(double val, int flag1, int flag2)
// simple_func: takes a value and calculates the expected ASIC output,
// given the two mode flags.
{
if (flag1 > 0)
return func1_muon(val, flag2);
if (flag1 == -1)
// handled by func1_tau: flag1 = -flag1;
return func1_tau(-val, flag1, flag2);
return 0.;
}
##### Note
"It doesn't fit on a screen" is often a good practical definition of "far too large."
One-to-five-line functions should be considered normal.
##### Note
Break large functions up into smaller cohesive and named functions.
Small simple functions are easily inlined where the cost of a function call is significant.
##### Enforcement
* Flag functions that do not "fit on a screen."
How big is a screen? Try 60 lines by 140 characters; that's roughly the maximum that's comfortable for a book page.
* 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`
##### Reason
`constexpr` is needed to tell the compiler to allow compile-time evaluation.
##### Example
The (in)famous factorial:
constexpr int fac(int n)
{
constexpr int max_exp = 17; // constexpr enables max_exp to be used in Expects
Expects(0 <= n && n < max_exp); // prevent silliness and overflow
int x = 1;
for (int i = 2; i <= n; ++i) x *= i;
return x;
}
This is C++14.
For C++11, use a recursive formulation of `fac()`.
##### Note
`constexpr` does not guarantee compile-time evaluation;
it just guarantees that the function can be evaluated at compile time for constant expression arguments if the programmer requires it or the compiler decides to do so to optimize.
constexpr int min(int x, int y) { return x < y ? x : y; }
void test(int v)
{
int m1 = min(-1, 2); // probably compile-time evaluation
constexpr int m2 = min(-1, 2); // compile-time evaluation
int m3 = min(-1, v); // run-time evaluation
constexpr int m4 = min(-1, v); // error: cannot evaluate at compile time
}
##### Note
Don't try to make all functions `constexpr`.
Most computation is best done at run time.
##### Note
Any API that might eventually depend on high-level run-time configuration or
business logic should not be made `constexpr`. Such customization can not be
evaluated by the compiler, and any `constexpr` functions that depended upon
that API would have to be refactored or drop `constexpr`.
##### Enforcement
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`
##### Reason
Some optimizers are good at inlining without hints from the programmer, but don't rely on it.
Measure! Over the last 40 years or so, we have been promised compilers that can inline better than humans without hints from humans.
We are still waiting.
Specifying inline (explicitly, or implicitly when writing member functions inside a class definition) encourages the compiler to do a better job.
##### Example
inline string cat(const string& s, const string& s2) { return s + s2; }
##### Exception
Do not put an `inline` function in what is meant to be a stable interface unless you are certain that it will not change.
An inline function is part of the ABI.
##### Note
`constexpr` implies `inline`.
##### Note
Member functions defined in-class are `inline` by default.
##### Exception
Function templates (including member functions of class templates `A::function()` and member function templates `A::function()`) are normally defined in headers and therefore inline.
##### Note
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`
##### Reason
If an exception is not supposed to be thrown, the program cannot be assumed to cope with the error and should be terminated as soon as possible. Declaring a function `noexcept` helps optimizers by reducing the number of alternative execution paths. It also speeds up the exit after failure.
##### Example
Put `noexcept` on every function written completely in C or in any other language without exceptions.
The C++ Standard Library does that implicitly for all functions in the C Standard Library.
##### Note
`constexpr` functions can throw when evaluated at run time, so you might need conditional `noexcept` for some of those.
##### Example
You can use `noexcept` even on functions that can throw:
vector collect(istream& is) noexcept
{
vector res;
for (string s; is >> s;)
res.push_back(s);
return res;
}
If `collect()` runs out of memory, the program crashes.
Unless the program is crafted to survive memory exhaustion, that might be just the right thing to do;
`terminate()` might generate suitable error log information (but after memory runs out it is hard to do anything clever).
##### Note
You must be aware of the execution environment that your code is running when
deciding whether to tag a function `noexcept`, especially because of the issue
of throwing and allocation. Code that is intended to be perfectly general (like
the standard library and other utility code of that sort) needs to support
environments where a `bad_alloc` exception could be handled meaningfully.
However, most programs and execution environments cannot meaningfully
handle a failure to allocate, and aborting the program is the cleanest and
simplest response to an allocation failure in those cases. If you know that
your application code cannot respond to an allocation failure, it could be
appropriate to add `noexcept` even on functions that allocate.
Put another way: In most programs, most functions can throw (e.g., because they
use `new`, call functions that do, or use library functions that report failure
by throwing), so don't just sprinkle `noexcept` all over the place without
considering whether the possible exceptions can be handled.
`noexcept` is most useful (and most clearly correct) for frequently used,
low-level functions.
##### Note
Destructors, `swap` functions, move operations, and default constructors should never throw.
See also [C.44](#rc-default00).
##### Note
Care must be taken on base virtual functions and functions part of a public interface because declaring a function `noexcept` is establishing a guarantee that all current and future implementations must abide by. For virtual function, all overriders must also be `noexcept` and removing `noexcept` from a function could break calling functions.
##### Enforcement
* (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
##### Reason
Passing a smart pointer transfers or shares ownership and should only be used when ownership semantics are intended.
A function that does not manipulate lifetime should take raw pointers or references instead.
Passing by smart pointer restricts the use of a function to callers that use smart pointers.
A function that needs a `widget` should be able to accept any `widget` object, not just ones whose lifetimes are managed by a particular kind of smart pointer.
Passing a shared smart pointer (e.g., `std::shared_ptr`) implies a run-time cost.
##### Example
// accepts any int*
void f(int*);
// can only accept ints for which you want to transfer ownership
void g(unique_ptr);
// can only accept ints for which you are willing to share ownership
void g(shared_ptr);
// doesn't change ownership, but requires a particular ownership of the caller
void h(const unique_ptr&);
// accepts any int
void h(int&);
##### Example, bad
// callee
void f(shared_ptr& w)
{
// ...
use(*w); // only use of w -- the lifetime is not used at all
// ...
};
// caller
shared_ptr my_widget = /* ... */;
f(my_widget);
widget stack_widget;
f(stack_widget); // error
##### Example, good
// callee
void f(widget& w)
{
// ...
use(w);
// ...
};
// caller
shared_ptr my_widget = /* ... */;
f(*my_widget);
widget stack_widget;
f(stack_widget); // ok -- now this works
##### 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.
##### Enforcement
* (Simple) Warn if a function takes a parameter of a smart pointer type (that overloads `operator->` or `operator*`) that is copyable but the function only calls any of: `operator*`, `operator->` or `get()`.
Suggest using a `T*` or `T&` instead.
* Flag a parameter of a smart pointer type (a type that overloads `operator->` or `operator*`) that is copyable/movable but never copied/moved from in the function body, and that is never modified, and that is not passed along to another function that could do so. That means the ownership semantics are not used.
Suggest using a `T*` or `T&` instead.
**See also**:
* [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
##### Reason
Pure functions are easier to reason about, sometimes easier to optimize (and even parallelize), and sometimes can be memoized.
##### Example
template
auto square(T t) { return t * t; }
##### Enforcement
Not possible.
### F.9: Unused parameters should be unnamed
##### Reason
Readability.
Suppression of unused parameter warnings.
##### Example
widget* find(const set& s, const widget& w, Hint); // once upon a time, a hint was used
##### Note
Allowing parameters to be unnamed was introduced in the early 1980s to address this problem.
If parameters are conditionally unused, declare them with the `[[maybe_unused]]` attribute.
For example:
template
Value* find(const set& s, const Value& v, [[maybe_unused]] Hint h)
{
if constexpr (sizeof(Value) > CacheSize)
{
// a hint is used only if Value is of a certain size
}
}
##### Enforcement
Flag named unused parameters.
### F.10: If an operation can be reused, give it a name
##### Reason
Documentation, readability, opportunity for reuse.
##### Example
struct Rec {
string name;
string addr;
int id; // unique identifier
};
bool same(const Rec& a, const Rec& b)
{
return a.id == b.id;
}
vector find_id(const string& name); // find all records for "name"
auto x = find_if(vr.begin(), vr.end(),
[&](Rec& r) {
if (r.name.size() != n.size()) return false; // name to compare to is in n
for (int i = 0; i < r.name.size(); ++i)
if (tolower(r.name[i]) != tolower(n[i])) return false;
return true;
}
);
There is a useful function lurking here (case insensitive string comparison), as there often is when lambda arguments get large.
bool compare_insensitive(const string& a, const string& b)
{
if (a.size() != b.size()) return false;
for (int i = 0; i < a.size(); ++i) if (tolower(a[i]) != tolower(b[i])) return false;
return true;
}
auto x = find_if(vr.begin(), vr.end(),
[&](Rec& r) { return compare_insensitive(r.name, n); }
);
Or maybe (if you prefer to avoid the implicit name binding to n):
auto cmp_to_n = [&n](const string& a) { return compare_insensitive(a, n); };
auto x = find_if(vr.begin(), vr.end(),
[](const Rec& r) { return cmp_to_n(r.name); }
);
##### Note
whether functions, lambdas, or operators.
##### Exception
* Lambdas logically used only locally, such as an argument to `for_each` and similar control flow algorithms.
* Lambdas as [initializers](#???)
##### Enforcement
* (hard) flag similar lambdas
* ???
### F.11: Use an unnamed lambda if you need a simple function object in one place only
##### Reason
That makes the code concise and gives better locality than alternatives.
##### Example
auto earlyUsersEnd = std::remove_if(users.begin(), users.end(),
[](const User &a) { return a.id > 100; });
##### Exception
Naming a lambda can be useful for clarity even if it is used only once.
##### Enforcement
* Look for identical and near identical lambdas (to be replaced with named functions or named lambdas).
## 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
##### Reason
Using "unusual and clever" techniques causes surprises, slows understanding by other programmers, and encourages bugs.
If you really feel the need for an optimization beyond the common techniques, measure to ensure that it really is an improvement, and document/comment because the improvement might not be portable.
The following tables summarize the advice in the following Guidelines, F.16-21.
Normal parameter passing:
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).
##### 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).
### F.16: For "in" parameters, pass cheaply-copied types by value and others by reference to `const`
##### Reason
Both let the caller know that a function will not modify the argument, and both allow initialization by rvalues.
What is "cheap to copy" depends on the machine architecture, but two or three words (doubles, pointers, references) are usually best passed by value.
When copying is cheap, nothing beats the simplicity and safety of copying, and for small objects (up to two or three words) it is also faster than passing by reference because it does not require an extra indirection to access from the function.
##### Example
void f1(const string& s); // OK: pass by reference to const; always cheap
void f2(string s); // bad: potentially expensive
void f3(int x); // OK: Unbeatable
void f4(const int& x); // bad: overhead on access in f4()
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 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).
##### Example
int multiply(int, int); // just input ints, pass by value
// suffix is input-only but not as cheap as an int, pass by const&
string& concatenate(string&, const string& suffix);
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)).
##### Notes
A reference can be assumed to refer to a valid object (language rule).
There is no (legitimate) "null reference."
If you need the notion of an optional value, use a pointer, `std::optional`, or a special value used to denote "no value."
##### Enforcement
* (Simple) ((Foundation)) Warn when a parameter being passed by value has a size greater than `2 * sizeof(void*)`.
Suggest using a reference to `const` instead.
* (Simple) ((Foundation)) Warn when a parameter passed by reference to `const` has a size less or equal than `2 * sizeof(void*)`. Suggest passing by value instead.
* (Simple) ((Foundation)) Warn when a parameter passed by reference to `const` is `move`d.
##### Exception
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`
##### Reason
This makes it clear to callers that the object is assumed to be modified.
##### Example
void update(Record& r); // assume that update writes to r
##### 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
mutable (in-out) reference semantics:
void increment_all(span a)
{
for (auto&& e : a)
++e;
}
##### Note
A `T&` argument can pass information into a function as well as out of it.
Thus `T&` could be an in-out-parameter. That can in itself be a problem and a source of errors:
void f(string& s)
{
s = "New York"; // non-obvious error
}
void g()
{
string buffer = ".................................";
f(buffer);
// ...
}
Here, the writer of `g()` is supplying a buffer for `f()` to fill, but `f()` simply replaces it (at a somewhat higher cost than a simple copy of the characters).
A bad logic error can happen if the writer of `g()` incorrectly assumes the size of the `buffer`.
##### Enforcement
* (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
##### Reason
It's efficient and eliminates bugs at the call site: `X&&` binds to rvalues, which requires an explicit `std::move` at the call site if passing an lvalue.
##### Example
void sink(vector&& v) // sink takes ownership of whatever the argument owned
{
// usually there might be const accesses of v here
store_somewhere(std::move(v));
// usually no more use of v here; it is moved-from
}
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).
##### Exception
Unique owner types that are move-only and cheap-to-move, such as `unique_ptr`, can also be passed by value which is simpler to write and achieves the same effect. Passing by value does generate one extra (cheap) move operation, but prefer simplicity and clarity first.
For example:
template
void sink(std::unique_ptr p)
{
// use p ... possibly std::move(p) onward somewhere else
} // p gets destroyed
##### Exception
If the "will-move-from" parameter is a `shared_ptr` follow [R.34](#rr-sharedptrparam-owner) and pass the `shared_ptr` by value.
##### Enforcement
* Flag all `X&&` parameters (where `X` is not a template type parameter name) where the function body uses them without `std::move`.
* 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
##### Reason
If the object is to be passed onward to other code and not directly used by this function, we want to make this function agnostic to the argument `const`-ness and rvalue-ness.
In that case, and only that case, make the parameter `TP&&` where `TP` is a template type parameter -- it both *ignores* and *preserves* `const`-ness and rvalue-ness. Therefore any code that uses a `TP&&` is implicitly declaring that it itself doesn't care about the variable's `const`-ness and rvalue-ness (because it is ignored), but that intends to pass the value onward to other code that does care about `const`-ness and rvalue-ness (because it is preserved). When used as a parameter `TP&&` is safe because any temporary objects passed from the caller will live for the duration of the function call. A parameter of type `TP&&` should essentially always be passed onward via `std::forward` in the body of the function.
##### Example
Usually you forward the entire parameter (or parameter pack, using `...`) exactly once on every static control flow path:
template
inline decltype(auto) invoke(F&& f, Args&&... args)
{
return forward(f)(forward(args)...);
}
##### Example
Sometimes you may forward a composite parameter piecewise, each subobject once on every static control flow path:
template
inline auto test(PairLike&& pairlike)
{
// ...
f1(some, args, and, forward(pairlike).first); // forward .first
f2(and, forward(pairlike).second, in, another, call); // forward .second
}
##### Enforcement
* 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
##### Reason
A return value is self-documenting, whereas an `&` could be either in-out or out-only and is liable to be misused.
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.
##### Example
// OK: return pointers to elements with the value x
vector find_all(const vector&, int x);
// Bad: place pointers to elements with value x in-out
void find_all(const vector&, vector& out, int x);
##### Note
A `struct` of many (individually cheap-to-move) elements might be in aggregate expensive to move.
##### Exceptions
* 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).
##### Example
Assuming that `Matrix` has move operations (possibly by keeping its elements in a `std::vector`):
Matrix operator+(const Matrix& a, const Matrix& b)
{
Matrix res;
// ... fill res with the sum ...
return res;
}
Matrix x = m1 + m2; // move constructor
y = m3 + m3; // move assignment
##### Note
The return value optimization doesn't handle the assignment case, but the move assignment does.
##### Example
struct Package { // exceptional case: expensive-to-move object
char header[16];
char load[2024 - 16];
};
Package fill(); // Bad: large return value
void fill(Package&); // OK
int val(); // OK
void val(int&); // Bad: Is val reading its argument
##### Enforcement
* 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
##### Reason
A return value is self-documenting as an "output-only" value.
Note that C++ does have multiple return values, by convention of using tuple-like types (`struct`, `array`, `tuple`, etc.),
possibly with the extra convenience of structured bindings (C++17) at the call site.
Prefer using a named `struct` if possible.
Otherwise, a `tuple` is useful in variadic templates.
##### Example
// BAD: output-only parameter documented in a comment
int f(const string& input, /*output only*/ string& output_data)
{
// ...
output_data = something();
return status;
}
// GOOD: self-documenting
struct f_result { int status; string data; };
f_result f(const string& input)
{
// ...
return {status, something()};
}
C++98's standard library used this style in places, by returning `pair` in some functions.
For example, given a `set my_set`, consider:
// C++98
pair result = my_set.insert("Hello");
if (result.second)
do_something_with(result.first); // workaround
With C++17 we are able to use "structured bindings" to give each member a name:
if (auto [ iter, success ] = my_set.insert("Hello"); success)
do_something_with(iter);
A `struct` with meaningful names is more common in modern C++.
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.
Explicitly passing an in-out parameter back out again as a return value is often not necessary.
For example:
istream& operator>>(istream& in, string& s); // much like std::operator>>()
for (string s; in >> s; ) {
// do something with line
}
Here, both `s` and `in` are used as in-out parameters.
We pass `in` by (non-`const`) reference to be able to manipulate its state.
We pass `s` to avoid repeated allocations.
By reusing `s` (passed by reference), we allocate new memory only when we need to expand `s`'s capacity.
This technique is sometimes called the "caller-allocated out" pattern and is particularly useful for types,
such as `string` and `vector`, that need to do free store allocations.
To compare, if we passed out all values as return values, we would write something like this:
struct get_string_result { istream& in; string s; };
get_string_result get_string(istream& in) // not recommended
{
string s;
in >> s;
return { in, move(s) };
}
for (auto [in, s] = get_string(cin); in; s = get_string(in).s) {
// do something with string
}
We consider that significantly less elegant with significantly less performance.
For a truly strict reading of this rule (F.21), the exception isn't really an exception because it relies on in-out parameters,
rather than the plain out parameters mentioned in the rule.
However, we prefer to be explicit, rather than subtle.
##### Note
In most cases, it is useful to return a specific, user-defined type.
For example:
struct Distance {
int value;
int unit = 1; // 1 means meters
};
Distance d1 = measure(obj1); // access d1.value and d1.unit
auto d2 = measure(obj2); // access d2.value and d2.unit
auto [value, unit] = measure(obj3); // access value and unit; somewhat redundant
// to people who know measure()
auto [x, y] = measure(obj4); // don't; it's likely to be confusing
The overly generic `pair` and `tuple` should be used only when the value returned represents independent entities rather than an abstraction.
Another option is to use `optional` or `expected`, rather than `pair` or `tuple`.
When used appropriately these types convey more information about what the members mean than `pair` or `pair` do.
##### Note
When the object to be returned is initialized from local variables that are expensive to copy,
explicit `move` may be helpful to avoid copying:
pair f(const string& input)
{
LargeObject large1 = g(input);
LargeObject large2 = h(input);
// ...
return { move(large1), move(large2) }; // no copies
}
Alternatively,
pair f(const string& input)
{
// ...
return { g(input), h(input) }; // no copies, no moves
}
Note this is different from the `return move(...)` anti-pattern from [ES.56](#res-move).
##### Enforcement
* Output parameters should be replaced by return values.
An output parameter is one that the function writes to, invokes a non-`const` member function, or passes on as a non-`const`.
* `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
##### Reason
A pointer (`T*`) can be a `nullptr` and a reference (`T&`) cannot, there is no valid "null reference".
Sometimes having `nullptr` as an alternative to indicated "no object" is useful, but if it is not, a reference is notationally simpler and might yield better code.
##### Example
string zstring_to_string(zstring p) // zstring is a char*; that is a C-style string
{
if (!p) return string{}; // p might be nullptr; remember to check
return string{p};
}
void print(const vector& r)
{
// r refers to a vector; no check needed
}
##### Note
It is possible, but not valid C++ to construct a reference that is essentially a `nullptr` (e.g., `T* p = nullptr; T& r = *p;`).
That error is very uncommon.
##### Note
If you prefer the pointer notation (`->` and/or `*` vs. `.`), `not_null` provides the same guarantee as `T&`.
##### Enforcement
* Flag ???
### F.22: Use `T*` or `owner` to designate a single object
##### Reason
Readability: it makes the meaning of a plain pointer clear.
Enables significant tool support.
##### Note
In traditional C and C++ code, plain `T*` is used for many weakly-related purposes, such as:
* Identify a (single) object (not to be deleted by this function)
* Point to an object allocated on the free store (and delete it later)
* Hold the `nullptr`
* Identify a C-style string (zero-terminated array of characters)
* Identify an array with a length specified separately
* Identify a location in an array
This makes it hard to understand what the code does and is supposed to do.
It complicates checking and tool support.
##### Example
void use(int* p, int n, char* s, int* q)
{
p[n - 1] = 666; // Bad: we don't know if p points to n elements;
// assume it does not or use span
cout << s; // Bad: we don't know if that s points to a zero-terminated array of char;
// assume it does not or use zstring
delete q; // Bad: we don't know if *q is allocated on the free store;
// assume it does not or use owner
}
better
void use2(span p, zstring s, owner q)
{
p[p.size() - 1] = 666; // OK, a range error can be caught
cout << s; // OK
delete q; // OK
}
##### Note
`owner` represents ownership, `zstring` represents a C-style string.
**Also**: Assume that a `T*` obtained from a smart pointer to `T` (e.g., `unique_ptr`) points to a single element.
**See also**: [Support library](#gsl-guidelines-support-library)
**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
##### Reason
Clarity. A function with a `not_null` parameter makes it clear that the caller of the function is responsible for any `nullptr` checks that might be necessary.
Similarly, a function with a return value of `not_null` makes it clear that the caller of the function does not need to check for `nullptr`.
##### Example
`not_null` makes it obvious to a reader (human or machine) that a test for `nullptr` is not necessary before dereference.
Additionally, when debugging, `owner` and `not_null` can be instrumented to check for correctness.
Consider:
int length(Record* p);
When I call `length(p)` should I check if `p` is `nullptr` first? Should the implementation of `length()` check if `p` is `nullptr`?
// it is the caller's job to make sure p != nullptr
int length(not_null p);
// the implementor of length() must assume that p == nullptr is possible
int length(Record* p);
##### Note
A `not_null` is assumed not to be the `nullptr`; a `T*` might be the `nullptr`; both can be represented in memory as a `T*` (so no run-time overhead is implied).
##### Note
`not_null` is not just for built-in pointers. It works for `unique_ptr`, `shared_ptr`, and other pointer-like types.
##### Enforcement
* (Simple) Warn if a raw pointer is dereferenced without being tested against `nullptr` (or equivalent) within a function, suggest it is declared `not_null` instead.
* (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
##### Reason
Informal/non-explicit ranges are a source of errors.
##### Example
X* find(span r, const X& v); // find v in r
vector vec;
// ...
auto p = find({vec.begin(), vec.end()}, X{}); // find X{} in vec
##### Note
Ranges are extremely common in C++ code. Typically, they are implicit and their correct use is very hard to ensure.
In particular, given a pair of arguments `(p, n)` designating an array `[p:p+n)`,
it is in general impossible to know if there really are `n` elements to access following `*p`.
`span` and `span_p` are simple helper classes designating a `[p:q)` range and a range starting with `p` and ending with the first element for which a predicate is true, respectively.
##### Example
A `span` represents a range of elements, but how do we manipulate elements of that range?
void f(span s)
{
// range traversal (guaranteed correct)
for (int x : s) cout << x << '\n';
// C-style traversal (potentially checked)
for (gsl::index i = 0; i < s.size(); ++i) cout << s[i] << '\n';
// random access (potentially checked)
s[7] = 9;
// extract pointers (potentially checked)
std::sort(&s[0], &s[s.size() / 2]);
}
##### Note
A `span` object does not own its elements and is so small that it can be passed by value.
Passing a `span` object as an argument is exactly as efficient as passing a pair of pointer arguments or passing a pointer and an integer count.
**See also**: [Support library](#gsl-guidelines-support-library)
##### Enforcement
(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
##### Reason
C-style strings are ubiquitous. They are defined by convention: zero-terminated arrays of characters.
We must distinguish C-style strings from a pointer to a single character or an old-fashioned pointer to an array of characters.
If you don't need null termination, use `string_view`.
##### Example
Consider:
int length(const char* p);
When I call `length(s)` should I check if `s` is `nullptr` first? Should the implementation of `length()` check if `p` is `nullptr`?
// the implementor of length() must assume that p == nullptr is possible
int length(zstring p);
// it is the caller's job to make sure p != nullptr
int length(not_null p);
##### Note
`zstring` does not represent ownership.
**See also**: [Support library](#gsl-guidelines-support-library)
### 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.
##### Example
unique_ptr get_shape(istream& is) // assemble shape from input stream
{
auto kind = read_header(is); // read header and identify the next shape on input
switch (kind) {
case kCircle:
return make_unique(is);
case kTriangle:
return make_unique(is);
// ...
}
}
##### Note
You need to pass a pointer rather than an object if what you are transferring is an object from a class hierarchy that is to be used through an interface (base class).
##### Enforcement
(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
##### Reason
Using `std::shared_ptr` is the standard way to represent shared ownership. That is, the last owner deletes the object.
##### Example
{
shared_ptr im { read_image(somewhere) };
std::thread t0 {shade, args0, top_left, im};
std::thread t1 {shade, args1, top_right, im};
std::thread t2 {shade, args2, bottom_left, im};
std::thread t3 {shade, args3, bottom_right, im};
// detaching threads requires extra care (e.g., to join before
// main ends), but even if we do detach the four threads here ...
}
// ... shared_ptr ensures that eventually the last thread to
// finish safely deletes the image
##### Note
Prefer a `unique_ptr` over a `shared_ptr` if there is never more than one owner at a time.
`shared_ptr` is for shared ownership.
Note that pervasive use of `shared_ptr` has a cost (atomic operations on the `shared_ptr`'s reference count have a measurable aggregate cost).
##### Alternative
Have a single object own the shared object (e.g. a scoped object) and destroy that (preferably implicitly) when all users have completed.
##### Enforcement
(Not enforceable) This is a too complex pattern to reliably detect.
### F.42: Return a `T*` to indicate a position (only)
##### Reason
That's what pointers are good for.
Returning a `T*` to transfer ownership is a misuse.
##### Example
Node* find(Node* t, const string& s) // find s in a binary tree of Nodes
{
if (!t || t->name == s) return t;
if ((auto p = find(t->left, s))) return p;
if ((auto p = find(t->right, s))) return p;
return nullptr;
}
If it isn't the `nullptr`, the pointer returned by `find` indicates a `Node` holding `s`.
Importantly, that does not imply a transfer of ownership of the pointed-to object to the caller.
##### 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).
##### Note
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](#???)
##### Enforcement
* Flag `delete`, `std::free()`, etc. applied to a plain `T*`.
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
##### Reason
To avoid the crashes and data corruption that can result from the use of such a dangling pointer.
##### Example, bad
After the return from a function its local objects no longer exist:
int* f()
{
int fx = 9;
return &fx; // BAD
}
void g(int* p) // looks innocent enough
{
int gx;
cout << "*p == " << *p << '\n';
*p = 999;
cout << "gx == " << gx << '\n';
}
void h()
{
int* p = f();
int z = *p; // read from abandoned stack frame (bad)
g(p); // pass pointer to abandoned stack frame to function (bad)
}
Here on one popular implementation I got the output:
*p == 999
gx == 999
I expected that because the call of `g()` reuses the stack space abandoned by the call of `f()` so `*p` refers to the space now occupied by `gx`.
* Imagine what would happen if `fx` and `gx` were of different types.
* Imagine what would happen if `fx` or `gx` was a type with an invariant.
* Imagine what would happen if that dangling pointer was passed around among a larger set of functions.
* Imagine what a cracker could do with that dangling pointer.
Fortunately, most (all?) modern compilers catch and warn against this simple case.
##### Note
This applies to references as well:
int& f()
{
int x = 7;
// ...
return x; // Bad: returns reference to object that is about to be destroyed
}
##### Note
This applies only to non-`static` local variables.
All `static` variables are (as their name indicates) statically allocated, so that pointers to them cannot dangle.
##### Example, bad
Not all examples of leaking a pointer to a local variable are that obvious:
int* glob; // global variables are bad in so many ways
template
void steal(T x)
{
glob = x(); // BAD
}
void f()
{
int i = 99;
steal([&] { return &i; });
}
int main()
{
f();
cout << *glob << '\n';
}
Here I managed to read the location abandoned by the call of `f`.
The pointer stored in `glob` could be used much later and cause trouble in unpredictable ways.
##### Note
The address of a local variable can be "returned"/leaked by a return statement, by a `T&` out-parameter, as a member of a returned object, as an element of a returned array, and more.
##### Note
Similar examples can be constructed "leaking" a pointer from an inner scope to an outer one;
such examples are handled equivalently to leaks of pointers out of a function.
A slightly different variant of the problem is placing pointers in a container that outlives the objects pointed to.
**See also**: Another way of getting dangling pointers is [pointer invalidation](#???).
It can be detected/prevented with similar techniques.
##### Enforcement
* 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
##### Reason
The language guarantees that a `T&` refers to an object, so that testing for `nullptr` isn't necessary.
**See also**: The return of a reference must not imply transfer of ownership:
[discussion of dangling pointer prevention](#???) and [discussion of ownership](#???).
##### Example
class Car
{
array w;
// ...
public:
wheel& get_wheel(int i) { Expects(i < w.size()); return w[i]; }
// ...
};
void use()
{
Car c;
wheel& w0 = c.get_wheel(0); // w0 has the same lifetime as c
}
##### Enforcement
Flag functions where no `return` expression could yield `nullptr`.
### F.45: Don't return a `T&&`
##### Reason
It's asking to return a reference to a destroyed temporary object.
An `&&` is a magnet for temporary objects.
##### Example
A returned rvalue reference goes out of scope at the end of the full expression to which it is returned:
auto&& x = max(0, 1); // OK, so far
foo(x); // Undefined behavior
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.
##### 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)).
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&&`).
Assume that `F` returns by value:
template
auto&& wrapper(F f)
{
log_call(typeid(f)); // or whatever instrumentation
return f(); // BAD: returns a reference to a temporary
}
Better:
template
auto wrapper(F f)
{
log_call(typeid(f)); // or whatever instrumentation
return f(); // OK
}
##### Exception
`std::move` and `std::forward` do return `&&`, but they are just casts -- used by convention only in expression contexts where a reference to a temporary object is passed along within the same expression before the temporary is destroyed. We don't know of any other good examples of returning `&&`.
##### Enforcement
Flag any use of `&&` as a return type, except in `std::move` and `std::forward`.
### F.46: `int` is the return type for `main()`
##### Reason
It's a language rule, but violated through "language extensions" so often that it is worth mentioning.
Declaring `main` (the one global `main` of a program) `void` limits portability.
##### Example
void main() { /* ... */ }; // bad, not C++
int main()
{
std::cout << "This is the way to do it\n";
}
##### Note
We mention this only because of the persistence of this error in the community.
Note that despite its non-void return type, the main function does not require an explicit return statement.
##### Enforcement
* The compiler should do it
* If the compiler doesn't do it, let tools flag it
### F.47: Return `T&` from assignment operators
##### Reason
The convention for operator overloads (especially on concrete types) is for
`operator=(const T&)` to perform the assignment and then return (non-`const`)
`*this`. This ensures consistency with standard-library types and follows the
principle of "do as the ints do."
##### Note
Historically there was some guidance to make the assignment operator return `const T&`.
This was primarily to avoid code of the form `(a = b) = c` -- such code is not common enough to warrant violating consistency with standard types.
##### Example
class Foo
{
public:
...
Foo& operator=(const Foo& rhs)
{
// Copy members.
...
return *this;
}
};
##### Enforcement
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)`
##### Reason
Returning a local variable implicitly moves it anyway.
An explicit `std::move` is always a pessimization, because it prevents Return Value Optimization (RVO),
which can eliminate the move completely.
##### Example, bad
S bad()
{
S result;
return std::move(result);
}
##### Example, good
S good()
{
S result;
// Named RVO: move elision at best, move construction at worst
return result;
}
##### Enforcement
This should be enforced by tooling by checking the return expression.
### F.49: Don't return `const T`
##### Reason
It is not recommended to return a `const` value.
Such older advice is now obsolete; it does not add value, and it interferes with move semantics.
##### Example
const vector fct(); // bad: that "const" is more trouble than it is worth
void g(vector& vx)
{
// ...
fct() = vx; // prevented by the "const"
// ...
vx = fct(); // expensive copy: move semantics suppressed by the "const"
// ...
}
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)
##### 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)
##### Reason
Functions can't capture local variables or be defined at local scope; if you need those things, prefer a lambda where possible, and a handwritten function object where not. On the other hand, lambdas and function objects don't overload; if you need to overload, prefer a function (the workarounds to make lambdas overload are ornate). If either will work, prefer writing a function; use the simplest tool necessary.
##### Example
// writing a function that should only take an int or a string
// -- overloading is natural
void f(int);
void f(const string&);
// writing a function object that needs to capture local state and appear
// at statement or expression scope -- a lambda is natural
vector v = lots_of_work();
for (int tasknum = 0; tasknum < max; ++tasknum) {
pool.run([=, &v] {
/*
...
... process (1/max)-th of v, the tasknum-th chunk
...
*/
});
}
pool.join();
##### Exception
Generic lambdas offer a concise way to write function templates and so can be useful even when a normal function template would do equally well with a little more syntax. This advantage will probably disappear in the future once all functions gain the ability to have Concept parameters.
##### Enforcement
* 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
##### Reason
Default arguments simply provide alternative interfaces to a single implementation.
There is no guarantee that a set of overloaded functions all implement the same semantics.
The use of default arguments can avoid code replication.
##### Note
There is a choice between using default argument and overloading when the alternatives are from a set of arguments of the same types.
For example:
void print(const string& s, format f = {});
as opposed to
void print(const string& s); // use default format
void print(const string& s, format f);
There is not a choice when a set of functions are used to do a semantically equivalent operation to a set of types. For example:
void print(const char&);
void print(int);
void print(zstring);
##### See also
[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
##### Reason
For efficiency and correctness, you nearly always want to capture by reference when using the lambda locally. This includes when writing or calling parallel algorithms that are local because they join before returning.
##### Discussion
The efficiency consideration is that most types are cheaper to pass by reference than by value.
The correctness consideration is that many calls want to perform side effects on the original object at the call site (see example below). Passing by value prevents this.
##### Note
Unfortunately, there is no simple way to capture by reference to `const` to get the efficiency for a local call but also prevent side effects.
##### Example
Here, a large object (a network message) is passed to an iterative algorithm, and it is not efficient or correct to copy the message (which might not be copyable):
std::for_each(begin(sockets), end(sockets), [&message](auto& socket)
{
socket.send(message);
});
##### Example
This is a simple three-stage parallel pipeline. Each `stage` object encapsulates a worker thread and a queue, has a `process` function to enqueue work, and in its destructor automatically blocks waiting for the queue to empty before ending the thread.
void send_packets(buffers& bufs)
{
stage encryptor([](buffer& b) { encrypt(b); });
stage compressor([&](buffer& b) { compress(b); encryptor.process(b); });
stage decorator([&](buffer& b) { decorate(b); compressor.process(b); });
for (auto& b : bufs) { decorator.process(b); }
} // automatically blocks waiting for pipeline to finish
##### Enforcement
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
##### Reason
Pointers and references to locals shouldn't outlive their scope. Lambdas that capture by reference are just another place to store a reference to a local object, and shouldn't do so if they (or a copy) outlive the scope.
##### Example, bad
int local = 42;
// Want a reference to local.
// Note that after program exits this scope,
// local no longer exists, therefore
// process() call will have undefined behavior!
thread_pool.queue_work([&] { process(local); });
##### Example, good
int local = 42;
// Want a copy of local.
// Since a copy of local is made, it will
// always be available for the call.
thread_pool.queue_work([=] { process(local); });
##### Note
If a non-local pointer must be captured, consider using `unique_ptr`; this handles both lifetime and synchronization.
If the `this` pointer must be captured, consider using `[*this]` capture, which creates a copy of the entire object.
##### Enforcement
* (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
##### Reason
It's confusing. Writing `[=]` in a member function appears to capture by value, but actually captures data members by reference because it actually captures the invisible `this` pointer by value. If you meant to do that, write `this` explicitly.
##### Example
class My_class {
int x = 0;
// ...
void f()
{
int i = 0;
// ...
auto lambda = [=] { use(i, x); }; // BAD: "looks like" copy/value capture
x = 42;
lambda(); // calls use(0, 42);
x = 43;
lambda(); // calls use(0, 43);
// ...
auto lambda2 = [i, this] { use(i, x); }; // ok, most explicit and least confusing
// ...
}
};
##### Note
If you intend to capture a copy of all class data members, consider C++17 `[*this]`.
##### Enforcement
* 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
##### Reason
Reading from a `va_arg` assumes that the correct type was actually passed.
Passing to varargs assumes the correct type will be read.
This is fragile because it cannot generally be enforced to be safe in the language and so relies on programmer discipline to get it right.
##### Example
int sum(...)
{
// ...
while (/*...*/)
result += va_arg(list, int); // BAD, assumes it will be passed ints
// ...
}
sum(3, 2); // ok
sum(3.14159, 2.71828); // BAD, undefined
template
auto sum(Args... args) // GOOD, and much more flexible
{
return (... + args); // note: C++17 "fold expression"
}
sum(3, 2); // ok: 5
sum(3.14159, 2.71828); // ok: ~5.85987
##### Alternatives
* overloading
* variadic templates
* `variant` arguments
* `initializer_list` (homogeneous)
##### Note
Declaring a `...` parameter is sometimes useful for techniques that don't involve actual argument passing, notably to declare "take-anything" functions so as to disable "everything else" in an overload set or express a catchall case in a template metaprogram.
##### Enforcement
* Issue a diagnostic for using `va_list`, `va_start`, or `va_arg`.
* 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
##### Reason
Shallow nesting of conditions makes the code easier to follow. It also makes the intent clearer.
Strive to place the essential code at outermost scope, unless this obscures intent.
##### Example
Use a guard-clause to take care of exceptional cases and return early.
// Bad: Deep nesting
void foo() {
...
if (x) {
computeImportantThings(x);
}
}
// Bad: Still a redundant else.
void foo() {
...
if (!x) {
return;
}
else {
computeImportantThings(x);
}
}
// Good: Early return, no redundant else
void foo() {
...
if (!x)
return;
computeImportantThings(x);
}
##### Example
// Bad: Unnecessary nesting of conditions
void foo() {
...
if (x) {
if (y) {
computeImportantThings(x);
}
}
}
// Good: Merge conditions + return early
void foo() {
...
if (!(x && y))
return;
computeImportantThings(x);
}
##### Enforcement
Flag a redundant `else`.
Flag a function whose body is simply a conditional statement enclosing a block.
# 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)
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.1: Organize related data into structures (`struct`s or `class`es)
##### Reason
Ease of comprehension.
If data is related (for fundamental reasons), that fact should be reflected in code.
##### Example
void draw(int x, int y, int x2, int y2); // BAD: unnecessary implicit relationships
void draw(Point from, Point to); // better
##### Note
A simple class without virtual functions implies no space or time overhead.
##### Note
From a language perspective `class` and `struct` differ only in the default visibility of their members.
##### Enforcement
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
##### Reason
Readability.
Ease of comprehension.
The use of `class` alerts the programmer to the need for an invariant.
This is a useful convention.
##### Note
An invariant is a logical condition for the members of an object that a constructor must establish for the public member functions to assume.
After the invariant is established (typically by a constructor) every member function can be called for the object.
An invariant can be stated informally (e.g., in a comment) or more formally using `Expects`.
If all data members can vary independently of each other, no invariant is possible.
##### Example
struct Pair { // the members can vary independently
string name;
int volume;
};
but:
class Date {
public:
// validate that {yy, mm, dd} is a valid date and initialize
Date(int yy, Month mm, char dd);
// ...
private:
int y;
Month m;
char d; // day
};
##### Note
If a class has any `private` data, a user cannot completely initialize an object without the use of a constructor.
Hence, the class definer will provide a constructor and must specify its meaning.
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)
##### 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
##### Reason
An explicit distinction between interface and implementation improves readability and simplifies maintenance.
##### Example
class Date {
public:
Date();
// validate that {yy, mm, dd} is a valid date and initialize
Date(int yy, Month mm, char dd);
int day() const;
Month month() const;
// ...
private:
// ... some representation ...
};
For example, we can now change the representation of a `Date` without affecting its users (recompilation is likely, though).
##### Note
Using a class in this way to represent the distinction between interface and implementation is of course not the only way.
For example, we can use a set of declarations of freestanding functions in a namespace, an abstract base class, or a function template with concepts to represent an interface.
The most important issue is to explicitly distinguish between an interface and its implementation "details."
Ideally, and typically, an interface is far more stable than its implementation(s).
##### Enforcement
???
### C.4: Make a function a member only if it needs direct access to the representation of a class
##### Reason
Less coupling than with member functions, fewer functions that can cause trouble by modifying object state, reduces the number of functions that need to be modified after a change in representation.
##### Example
class Date {
// ... relatively small interface ...
};
// helper functions:
Date next_weekday(Date);
bool operator==(Date, Date);
The "helper functions" have no need for direct access to the representation of a `Date`.
##### Note
This rule becomes even better if C++ gets ["uniform function call"](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0251r0.pdf).
##### Exception
The language requires `virtual` functions to be members, and not all `virtual` functions directly access data.
In particular, members of an abstract class rarely do.
Note [multi-methods](https://web.archive.org/web/20200605021759/https://parasol.tamu.edu/~yuriys/papers/OMM10.pdf).
##### Exception
The language requires operators `=`, `()`, `[]`, and `->` to be members.
##### Exception
An overload set could have some members that do not directly access `private` data:
class Foobar {
public:
void foo(long x) { /* manipulate private data */ }
void foo(double x) { foo(std::lround(x)); }
// ...
private:
// ...
};
##### Exception
Similarly, a set of functions could be designed to be used in a chain:
x.scale(0.5).rotate(45).set_color(Color::red);
Typically, some but not all of such functions directly access `private` data.
##### Enforcement
* Look for non-`virtual` member functions that do not touch data members directly.
The snag is that many member functions that do not need to touch data members directly do.
* Ignore `virtual` functions.
* 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
##### Reason
A helper function is a function (usually supplied by the writer of a class) that does not need direct access to the representation of the class, yet is seen as part of the useful interface to the class.
Placing them in the same namespace as the class makes their relationship to the class obvious and allows them to be found by argument dependent lookup.
##### Example
namespace Chrono { // here we keep time-related services
class Time { /* ... */ };
class Date { /* ... */ };
// helper functions:
bool operator==(Date, Date);
Date next_weekday(Date);
// ...
}
##### Note
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
##### Reason
Mixing a type definition and the definition of another entity in the same declaration is confusing and unnecessary.
##### Example, bad
struct Data { /*...*/ } data{ /*...*/ };
##### Example, good
struct Data { /*...*/ };
Data data{ /*...*/ };
##### Enforcement
* 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
##### Reason
Readability.
To make it clear that something is being hidden/abstracted.
This is a useful convention.
##### Example, bad
struct Date {
int d, m;
Date(int i, Month m);
// ... lots of functions ...
private:
int y; // year
};
There is nothing wrong with this code as far as the C++ language rules are concerned,
but nearly everything is wrong from a design perspective.
The private data is hidden far from the public data.
The data is split in different parts of the class declaration.
Different parts of the data have different access.
All of this decreases readability and complicates maintenance.
##### Note
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
##### Reason
Encapsulation.
Information hiding.
Minimize the chance of unintended access.
This simplifies maintenance.
##### Example
template
struct pair {
T a;
U b;
// ...
};
Whatever we do in the `//`-part, an arbitrary user of a `pair` can arbitrarily and independently change its `a` and `b`.
In a large code base, we cannot easily find which code does what to the members of `pair`.
This might be exactly what we want, but if we want to enforce a relation among members, we need to make them `private`
and enforce that relation (invariant) through constructors and member functions.
For example:
class Distance {
public:
// ...
double meters() const { return magnitude*unit; }
void set_unit(double u)
{
// ... check that u is a factor of 10 ...
// ... change magnitude appropriately ...
unit = u;
}
// ...
private:
double magnitude;
double unit; // 1 is meters, 1000 is kilometers, 0.001 is millimeters, etc.
};
##### Note
If the set of direct users of a set of variables cannot be easily determined, the type or usage of that set cannot be (easily) changed/improved.
For `public` and `protected` data, that's usually the case.
##### Example
A class can provide two interfaces to its users.
One for derived classes (`protected`) and one for general users (`public`).
For example, a derived class might be allowed to skip a run-time check because it has already guaranteed correctness:
class Foo {
public:
int bar(int x) { check(x); return do_bar(x); }
// ...
protected:
int do_bar(int x); // do some operation on the data
// ...
private:
// ... data ...
};
class Dir : public Foo {
//...
int mem(int x, int y)
{
/* ... do something ... */
return do_bar(x + y); // OK: derived class can bypass check
}
};
void user(Foo& x)
{
int r1 = x.bar(1); // OK, will check
int r2 = x.do_bar(2); // error: would bypass check
// ...
}
##### Note
[`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).
##### Enforcement
* [Flag protected data](#rh-protected).
* Flag mixtures of `public` and `private` data
## 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
##### Reason
A concrete type is fundamentally simpler than a type in a class hierarchy:
easier to design, easier to implement, easier to use, easier to reason about, smaller, and faster.
You need a reason (use cases) for using a hierarchy.
##### Example
class Point1 {
int x, y;
// ... operations ...
// ... no virtual functions ...
};
class Point2 {
int x, y;
// ... operations, some virtual ...
virtual ~Point2();
};
void use()
{
Point1 p11 {1, 2}; // make an object on the stack
Point1 p12 {p11}; // a copy
auto p21 = make_unique(1, 2); // make an object on the free store
auto p22 = p21->clone(); // make a copy
// ...
}
If a class is part of a hierarchy, we (in real code if not necessarily in small examples) must manipulate its objects through pointers or references.
That implies more memory overhead, more allocations and deallocations, and more run-time overhead to perform the resulting indirections.
##### Note
Concrete types can be stack-allocated and be members of other classes.
##### Note
The use of indirection is fundamental for run-time polymorphic interfaces.
The allocation/deallocation overhead is not (that's just the most common case).
We can use a base class as the interface of a scoped object of a derived class.
This is done where dynamic allocation is prohibited (e.g. hard-real-time) and to provide a stable interface to some kinds of plug-ins.
##### Enforcement
???
### C.11: Make concrete types regular
##### Reason
Regular types are easier to understand and reason about than types that are not regular (irregularities require extra effort to understand and use).
The C++ built-in types are regular, and so are standard-library classes such as `string`, `vector`, and `map`. Concrete classes without assignment and equality can be defined, but they are (and should be) rare.
##### Example
struct Bundle {
string name;
vector vr;
};
bool operator==(const Bundle& a, const Bundle& b)
{
return a.name == b.name && a.vr == b.vr;
}
Bundle b1 { "my bundle", {r1, r2, r3}};
Bundle b2 = b1;
if (!(b1 == b2)) error("impossible!");
b2.name = "the other bundle";
if (b1 == b2) error("No!");
In particular, if a concrete type is copyable, prefer to also give it an equality comparison operator, and ensure that `a = b` implies `a == b`.
##### Note
For structs intended to be shared with C code, defining `operator==` may not be feasible.
##### Note
Handles for resources that cannot be cloned, e.g., a `scoped_lock` for a `mutex`, are concrete types but typically cannot be copied (instead, they can usually be moved),
so they can't be regular; instead, they tend to be move-only.
##### Enforcement
???
### C.12: Don't make data members `const` or references in a copyable or movable type
##### Reason
`const` and reference data members are not useful in a copyable or movable type, and make such types difficult to use by making them at least partly uncopyable/unmovable for subtle reasons.
##### Example; bad
class bad {
const int i; // bad
string& s; // bad
// ...
};
The `const` and `&` data members make this class "only-sort-of-copyable" -- copy-constructible but not copy-assignable.
##### Note
If you need a member to point to something, use a pointer (raw or smart, and `gsl::not_null` if it should not be null) instead of a reference.
##### Enforcement
Flag a data member that is `const`, `&`, or `&&` in a type that has any copy or move operation.
## 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.
These are *default operations*:
* a default constructor: `X()`
* a copy constructor: `X(const X&)`
* a copy assignment: `operator=(const X&)`
* a move constructor: `X(X&&)`
* a move assignment: `operator=(X&&)`
* a destructor: `~X()`
By default, the compiler defines each of these operations if it is used, but the default can be suppressed.
The default operations are a set of related operations that together implement the lifecycle semantics of an object.
By default, C++ treats classes as value-like types, but not all types are value-like.
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)
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)
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)
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)
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.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
##### Reason
It's the simplest and gives the cleanest semantics.
##### Example
struct Named_map {
public:
explicit Named_map(const string& n) : name(n) {}
// no copy/move constructors
// no copy/move assignment operators
// no destructor
private:
string name;
map rep;
};
Named_map nm("map"); // construct
Named_map nm2 {nm}; // copy construct
Since `std::map` and `string` have all the special functions, no further work is needed.
##### Note
This is known as "the rule of zero".
##### Enforcement
(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
##### Reason
The semantics of copy, move, and destruction are closely related, so if one needs to be declared, the odds are that others need consideration too.
Declaring any copy/move/destructor function,
even as `=default` or `=delete`, will suppress the implicit declaration
of a move constructor and move assignment operator.
Declaring a move constructor or move assignment operator, even as
`=default` or `=delete`, will cause an implicitly generated copy constructor
or implicitly generated copy assignment operator to be defined as deleted.
So as soon as any of these are declared, the others should
all be declared to avoid unwanted effects like turning all potential moves
into more expensive copies, or making a class move-only.
##### Example, bad
struct M2 { // bad: incomplete set of copy/move/destructor operations
public:
// ...
// ... no copy or move operations ...
~M2() { delete[] rep; }
private:
pair* rep; // zero-terminated set of pairs
};
void use()
{
M2 x;
M2 y;
// ...
x = y; // the default assignment
// ...
}
Given that "special attention" was needed for the destructor (here, to deallocate), the likelihood that the implicitly-defined copy and move assignment operators will be correct is low (here, we would get double deletion).
##### Note
This is known as "the rule of five."
##### Note
If you want a default implementation (while defining another), write `=default` to show you're doing so intentionally for that function.
If you don't want a generated default function, suppress it with `=delete`.
##### Example, good
When a destructor needs to be declared just to make it `virtual`, it can be
defined as defaulted.
class AbstractBase {
public:
virtual void foo() = 0; // at least one abstract method to make the class abstract
virtual ~AbstractBase() = default;
// ...
};
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 {
public:
virtual unique_ptr clone() const;
virtual ~CloneableBase() = default;
CloneableBase() = default;
CloneableBase(const CloneableBase&) = delete;
CloneableBase& operator=(const CloneableBase&) = delete;
CloneableBase(CloneableBase&&) = delete;
CloneableBase& operator=(CloneableBase&&) = delete;
// ... other constructors and functions ...
};
Defining only the move operations or only the copy operations would have the
same effect here, but stating the intent explicitly for each special member
makes it more obvious to the reader.
##### Note
Compilers enforce much of this rule and ideally warn about any violation.
##### Note
Relying on an implicitly generated copy operation in a class with a destructor is deprecated.
##### Note
Writing these functions can be error-prone.
Note their argument types:
class X {
public:
// ...
virtual ~X() = default; // destructor (virtual if X is meant to be a base class)
X(const X&) = default; // copy constructor
X& operator=(const X&) = default; // copy assignment
X(X&&) noexcept = default; // move constructor
X& operator=(X&&) noexcept = default; // move assignment
};
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).
##### 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
##### Reason
The default operations are conceptually a matched set. Their semantics are interrelated.
Users will be surprised if copy/move construction and copy/move assignment do logically different things. Users will be surprised if constructors and destructors do not provide a consistent view of resource management. Users will be surprised if copy and move don't reflect the way constructors and destructors work.
##### Example, bad
class Silly { // BAD: Inconsistent copy operations
class Impl {
// ...
};
shared_ptr p;
public:
Silly(const Silly& a) : p(make_shared()) { *p = *a.p; } // deep copy
Silly& operator=(const Silly& a) { p = a.p; return *this; } // shallow copy
// ...
};
These operations disagree about copy semantics. This will lead to confusion and bugs.
##### Enforcement
* (Complex) A copy/move constructor and the corresponding copy/move assignment operator should write to the same data members at the same level of dereference.
* (Complex) Any data members written in a copy/move constructor should also be initialized by all other constructors.
* (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
"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);
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)).
### C.30: Define a destructor if a class needs an explicit action at object destruction
##### Reason
A destructor is implicitly invoked at the end of an object's lifetime.
If the default destructor is sufficient, use it.
Only define a non-default destructor if a class needs to execute code that is not already part of its members' destructors.
##### Example
template
struct final_action { // slightly simplified
A act;
final_action(A a) : act{a} {}
~final_action() { act(); }
};
template
final_action finally(A act) // deduce action type
{
return final_action{act};
}
void test()
{
auto act = finally([] { cout << "Exit test\n"; }); // establish exit action
// ...
if (something) return; // act done here
// ...
} // act done here
The whole purpose of `final_action` is to get a piece of code (usually a lambda) executed upon destruction.
##### Note
There are two general categories of classes that need a user-defined destructor:
* A class with a resource that is not already represented as a class with a destructor, e.g., a `vector` or a transaction class.
* A class that exists primarily to execute an action upon destruction, such as a tracer or `final_action`.
##### Example, bad
class Foo { // bad; use the default destructor
public:
// ...
~Foo() { s = ""; i = 0; vi.clear(); } // clean up
private:
string s;
int i;
vector vi;
};
The default destructor does it better, more efficiently, and can't get it wrong.
##### Enforcement
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
##### Reason
Prevention of resource leaks, especially in error cases.
##### Note
For resources represented as classes with a complete set of default operations, this happens automatically.
##### Example
class X {
ifstream f; // might own a file
// ... no default operations defined or =deleted ...
};
`X`'s `ifstream` implicitly closes any file it might have open upon destruction of its `X`.
##### Example, bad
class X2 { // bad
FILE* f; // might own a file
// ... no default operations defined or =deleted ...
};
`X2` might leak a file handle.
##### Note
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).
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.
##### Note
A class can hold pointers and references to objects that it does not own.
Obviously, such objects should not be `delete`d by the class's destructor.
For example:
Preprocessor pp { /* ... */ };
Parser p { pp, /* ... */ };
Type_checker tc { p, /* ... */ };
Here `p` refers to `pp` but does not own it.
##### Enforcement
* (Simple) If a class has pointer or reference members that are owners
(e.g., deemed owners by using `gsl::owner`), then they should be referenced in its destructor.
* (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
##### Reason
There is a lot of code that is non-specific about ownership.
##### Example
class legacy_class
{
foo* m_owning; // Bad: change to unique_ptr or owner
bar* m_observer; // OK: keep
}
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).
##### 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
##### Reason
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.
Consider a `T*` a possible owner and therefore suspect.
template
class Smart_ptr {
T* p; // BAD: vague about ownership of *p
// ...
public:
// ... no user-defined default operations ...
};
void use(Smart_ptr p1)
{
// error: p2.p leaked (if not nullptr and not owned by some other code)
auto p2 = p1;
}
Note that if you define a destructor, you must define or delete [all default operations](#rc-five):
template
class Smart_ptr2 {
T* p; // BAD: vague about ownership of *p
// ...
public:
// ... no user-defined copy operations ...
~Smart_ptr2() { delete p; } // p is an owner!
};
void use(Smart_ptr2 p1)
{
auto p2 = p1; // error: double deletion
}
The default copy operation will just copy the `p1.p` into `p2.p` leading to a double destruction of `p1.p`. Be explicit about ownership:
template
class Smart_ptr3 {
owner p; // OK: explicit about ownership of *p
// ...
public:
// ...
// ... copy and move operations ...
~Smart_ptr3() { delete p; }
};
void use(Smart_ptr3 p1)
{
auto p2 = p1; // OK: no double deletion
}
##### Note
Often the simplest way to get a destructor is to replace the pointer with a smart pointer (e.g., `std::unique_ptr`) and let the compiler arrange for proper destruction to be done implicitly.
##### Note
Why not just require all owning pointers to be "smart pointers"?
That would sometimes require non-trivial code changes and might affect ABIs.
##### Enforcement
* A class with a pointer data member is suspect.
* 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
##### Reason
To prevent undefined behavior.
If the destructor is public, then calling code can attempt to destroy a derived class object through a base class pointer, and the result is undefined if the base class's destructor is non-virtual.
If the destructor is protected, then calling code cannot destroy through a base class pointer and the destructor does not need to be virtual; it does need to be protected, not private, so that derived destructors can invoke it.
In general, the writer of a base class does not know the appropriate action to be done upon destruction.
##### Discussion
See [this in the Discussion section](#sd-dtor).
##### Example, bad
struct Base { // BAD: implicitly has a public non-virtual destructor
virtual void f();
};
struct D : Base {
string s {"a resource needing cleanup"};
~D() { /* ... do some cleanup ... */ }
// ...
};
void use()
{
unique_ptr p = make_unique();
// ...
} // p's destruction calls ~Base(), not ~D(), which leaks D::s and possibly more
##### Note
A virtual function defines an interface to derived classes that can be used without looking at the derived classes.
If the interface allows destroying, it should be safe to do so.
##### Note
A destructor must be non-private or it will prevent using the type:
class X {
~X(); // private destructor
// ...
};
void use()
{
X a; // error: cannot destroy
auto p = make_unique(); // error: cannot destroy
}
##### Exception
We can imagine one case where you could want a protected virtual destructor: When an object of a derived type (and only of such a type) should be allowed to destroy *another* object (not itself) through a pointer to base. We haven't seen such a case in practice, though.
##### Enforcement
* 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
##### Reason
In general we do not know how to write error-free code if a destructor should fail.
The standard library requires that all classes it deals with have destructors that do not exit by throwing.
##### Example
class X {
public:
~X() noexcept;
// ...
};
X::~X() noexcept
{
// ...
if (cannot_release_a_resource) terminate();
// ...
}
##### Note
Many have tried to devise a fool-proof scheme for dealing with failure in destructors.
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).
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.
##### Note
Declare a destructor `noexcept`. That will ensure that it either completes normally or terminates the program.
##### Note
If a resource cannot be released and the program must not fail, try to signal the failure to the rest of the system somehow
(maybe even by modifying some global state and hope something will notice and be able to take care of the problem).
Be fully aware that this technique is special-purpose and error-prone.
Consider the "my connection will not close" example.
Probably there is a problem at the other end of the connection and only a piece of code responsible for both ends of the connection can properly handle the problem.
The destructor could send a message (somehow) to the responsible part of the system, consider that to have closed the connection, and return normally.
##### Note
If a destructor uses operations that could fail, it can catch exceptions and in some cases still complete successfully
(e.g., by using a different clean-up mechanism from the one that threw an exception).
##### Enforcement
(Simple) A destructor should be declared `noexcept` if it could throw.
### 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.
##### Note
A destructor (either user-defined or compiler-generated) is implicitly declared `noexcept` (independently of what code is in its body) if all of the members of its class have `noexcept` destructors. By explicitly marking destructors `noexcept`, an author guards against the destructor becoming implicitly `noexcept(false)` through the addition or modification of a class member.
##### Example
Not all destructors are noexcept by default; one throwing member poisons the whole class hierarchy
struct X {
Details x; // happens to have a throwing destructor
// ...
~X() { } // implicitly noexcept(false); aka can throw
};
So, if in doubt, declare a destructor noexcept.
##### Note
Why not then declare all destructors noexcept?
Because that would in many cases -- especially simple cases -- be distracting clutter.
##### Enforcement
(Simple) A destructor should be declared `noexcept` if it could throw.
## C.ctor: Constructors
A constructor defines how an object is initialized (constructed).
### C.40: Define a constructor if a class has an invariant
##### Reason
That's what constructors are for.
##### Example
class Date { // a Date represents a valid date
// in the January 1, 1900 to December 31, 2100 range
Date(int dd, int mm, int yy)
:d{dd}, m{mm}, y{yy}
{
if (!is_valid(d, m, y)) throw Bad_date{}; // enforce invariant
}
// ...
private:
int d, m, y;
};
It is often a good idea to express the invariant as an `Ensures` on the constructor.
##### Note
A constructor can be used for convenience even if a class does not have an invariant. For example:
struct Rec {
string s;
int i {0};
Rec(const string& ss) : s{ss} {}
Rec(int ii) :i{ii} {}
};
Rec r1 {7};
Rec r2 {"Foo bar"};
##### Note
The C++11 initializer list rule eliminates the need for many constructors. For example:
struct Rec2{
string s;
int i;
Rec2(const string& ss, int ii = 0) :s{ss}, i{ii} {} // redundant
};
Rec2 r1 {"Foo", 7};
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).
**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
##### Reason
A constructor establishes the invariant for a class. A user of a class should be able to assume that a constructed object is usable.
##### Example, bad
class X1 {
FILE* f; // call init() before any other function
// ...
public:
X1() {}
void init(); // initialize f
void read(); // read from f
// ...
};
void f()
{
X1 file;
file.read(); // crash or bad read!
// ...
file.init(); // too late
// ...
}
Compilers do not read comments.
##### Exception
If a valid object cannot conveniently be constructed by a constructor, [use a factory function](#rc-factory).
##### Enforcement
* (Simple) Every constructor should initialize every data member (either explicitly, via a delegating ctor call or via default construction).
* (Unknown) If a constructor has an `Ensures` contract, try to see if it holds as a postcondition.
##### 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").
### C.42: If a constructor cannot construct a valid object, throw an exception
##### Reason
Leaving behind an invalid object is asking for trouble.
##### Example
class X2 {
FILE* f;
// ...
public:
X2(const string& name)
:f{fopen(name.c_str(), "r")}
{
if (!f) throw runtime_error{"could not open" + name};
// ...
}
void read(); // read from f
// ...
};
void f()
{
X2 file {"Zeno"}; // throws if file isn't open
file.read(); // fine
// ...
}
##### Example, bad
class X3 { // bad: the constructor leaves a non-valid object behind
FILE* f; // call is_valid() before any other function
bool valid;
// ...
public:
X3(const string& name)
:f{fopen(name.c_str(), "r")}, valid{false}
{
if (f) valid = true;
// ...
}
bool is_valid() { return valid; }
void read(); // read from f
// ...
};
void f()
{
X3 file {"Heraclides"};
file.read(); // crash or bad read!
// ...
if (file.is_valid()) {
file.read();
// ...
}
else {
// ... handle error ...
}
// ...
}
##### Note
For a variable definition (e.g., on the stack or as a member of another object) there is no explicit function call from which an error code could be returned.
Leaving behind an invalid object and relying on users to consistently check an `is_valid()` function before use is tedious, error-prone, and inefficient.
##### 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).
##### 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).
##### 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).
##### Enforcement
???
### C.43: Ensure that a copyable class has a default constructor
##### Reason
That is, ensure that if a concrete class is copyable it also satisfies the rest of "semiregular."
Many language and library facilities rely on default constructors to initialize their elements, e.g. `T a[10]` and `std::vector v(10)`.
A default constructor often simplifies the task of defining a suitable [moved-from state](#???) for a type that is also copyable.
##### Example
class Date { // BAD: no default constructor
public:
Date(int dd, int mm, int yyyy);
// ...
};
vector vd1(1000); // default Date needed here
vector vd2(1000, Date{7, Month::October, 1885}); // alternative
The default constructor is only auto-generated if there is no user-declared constructor, hence it's impossible to initialize the vector `vd1` in the example above.
The absence of a default value can cause surprises for users and complicate its use, so if one can be reasonably defined, it should be.
`Date` is chosen to encourage thought:
There is no "natural" default date (the big bang is too far back in time to be useful for most people), so this example is non-trivial.
`{0, 0, 0}` is not a valid date in most calendar systems, so choosing that would be introducing something like floating-point's `NaN`.
However, most realistic `Date` classes have a "first date" (e.g. January 1, 1970 is popular), so making that the default is usually trivial.
class Date {
public:
Date(int dd, int mm, int yyyy);
Date() = default; // [See also](#rc-default)
// ...
private:
int dd {1};
int mm {1};
int yyyy {1970};
// ...
};
vector vd1(1000);
##### Note
A class with members that all have default constructors implicitly gets a default constructor:
struct X {
string s;
vector v;
};
X x; // means X{ { }, { } }; that is the empty string and the empty vector
Beware that built-in types are not properly default constructed:
struct X {
string s;
int i;
};
void f()
{
X x; // x.s is initialized to the empty string; x.i is uninitialized
cout << x.s << ' ' << x.i << '\n';
++x.i;
}
Statically allocated objects of built-in types are by default initialized to `0`, but local built-in variables are not.
Beware that your compiler might default initialize local built-in variables, whereas an optimized build will not.
Thus, code like the example above might appear to work, but it relies on undefined behavior.
Assuming that you want initialization, an explicit default initialization can help:
struct X {
string s;
int i {}; // default initialize (to 0)
};
##### Notes
Classes that don't have a reasonable default construction are usually not copyable either, so they don't fall under this guideline.
For example, a base class should not be copyable, and so does not necessarily need a default constructor:
// Shape is an abstract base class, not a copyable type.
// It might or might not need a default constructor.
struct Shape {
virtual void draw() = 0;
virtual void rotate(int) = 0;
// =delete copy/move functions
// ...
};
A class that must acquire a caller-provided resource during construction often cannot have a default constructor, but it does not fall under this guideline because such a class is usually not copyable anyway:
// std::lock_guard is not a copyable type.
// It does not have a default constructor.
lock_guard g {mx}; // guard the mutex mx
lock_guard g2; // error: guarding nothing
A class that has a "special state" that must be handled separately from other states by member functions or users causes extra work
(and most likely more errors). Such a type can naturally use the special state as a default constructed value, whether or not it is copyable:
// std::ofstream is not a copyable type.
// It does happen to have a default constructor
// that goes along with a special "not open" state.
ofstream out {"Foobar"};
// ...
out << log(time, transaction);
Similar special-state types that are copyable, such as copyable smart pointers that have the special state "==nullptr", should use the special state as their default constructed value.
However, it is preferable to have a default constructor default to a meaningful state such as `std::string`s `""` and `std::vector`s `{}`.
##### Enforcement
* Flag classes that are copyable by `=` without a default constructor
* Flag classes that are comparable with `==` but not copyable
### C.44: Prefer default constructors to be simple and non-throwing
##### Reason
Being able to set a value to "the default" without operations that might fail simplifies error handling and reasoning about move operations.
##### Example, problematic
template
// elem points to space-elem element allocated using new
class Vector0 {
public:
Vector0() :Vector0{0} {}
Vector0(int n) :elem{new T[n]}, space{elem + n}, last{elem} {}
// ...
private:
own elem;
T* space;
T* last;
};
This is nice and general, but setting a `Vector0` to empty after an error involves an allocation, which might fail.
Also, having a default `Vector` represented as `{new T[0], 0, 0}` seems wasteful.
For example, `Vector0 v[100]` costs 100 allocations.
##### Example
template
// elem is nullptr or elem points to space-elem element allocated using new
class Vector1 {
public:
// sets the representation to {nullptr, nullptr, nullptr}; doesn't throw
Vector1() noexcept {}
Vector1(int n) :elem{new T[n]}, space{elem + n}, last{elem} {}
// ...
private:
own elem {};
T* space {};
T* last {};
};
Using `{nullptr, nullptr, nullptr}` makes `Vector1{}` cheap, but a special case and implies run-time checks.
Setting a `Vector1` to empty after detecting an error is trivial.
##### Enforcement
* Flag throwing default constructors
### C.45: Don't define a default constructor that only initializes data members; use default member initializers instead
##### Reason
Using default member initializers lets the compiler generate the function for you. The compiler-generated function can be more efficient.
##### Example, bad
class X1 { // BAD: doesn't use member initializers
string s;
int i;
public:
X1() :s{"default"}, i{1} { }
// ...
};
##### Example
class X2 {
string s {"default"};
int i {1};
public:
// use compiler-generated default constructor
// ...
};
##### Enforcement
(Simple) Flag if a default constructor's explicit member initializer is a constant, and recommend that the constant should be written as a data member initializer instead.
### C.46: By default, declare single-argument constructors explicit
##### Reason
To avoid unintended conversions.
##### Example, bad
class String {
public:
String(int); // BAD
// ...
};
String s = 10; // surprise: string of size 10
##### Exception
If you really want an implicit conversion from the constructor argument type to the class type, don't use `explicit`:
class Complex {
public:
Complex(double d); // OK: we want a conversion from d to {d, 0}
// ...
};
Complex z = 10.7; // unsurprising conversion
**See also**: [Discussion of implicit conversions](#ro-conversion)
##### Note
Copy and move constructors should not be made `explicit` because they do not perform conversions. Explicit copy/move constructors make passing and returning by value difficult.
##### Enforcement
(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
##### Reason
To minimize confusion and errors. That is the order in which the initialization happens (independent of the order of member initializers).
##### Example, bad
class Foo {
int m1;
int m2;
public:
Foo(int x) :m2{x}, m1{++x} { } // BAD: misleading initializer order
// ...
};
Foo x(1); // surprise: x.m1 == x.m2 == 2
##### Enforcement
(Simple) A member initializer list should mention the members in the same order they are declared.
**See also**: [Discussion](#sd-order)
### C.48: Prefer default member initializers to member initializers in constructors for constant initializers
##### Reason
Makes it explicit that the same value is expected to be used in all constructors. Avoids repetition. Avoids maintenance problems. It leads to the shortest and most efficient code.
##### Example, bad
class X { // BAD
int i;
string s;
int j;
public:
X() :i{666}, s{"qqq"} { } // j is uninitialized
X(int ii) :i{ii} {} // s is "" and j is uninitialized
// ...
};
How would a maintainer know whether `j` was deliberately uninitialized (probably a bad idea anyway) and whether it was intentional to give `s` the default value `""` in one case and `qqq` in another (almost certainly a bug)? The problem with `j` (forgetting to initialize a member) often happens when a new member is added to an existing class.
##### Example
class X2 {
int i {666};
string s {"qqq"};
int j {0};
public:
X2() = default; // all members are initialized to their defaults
X2(int ii) :i{ii} {} // s and j initialized to their defaults
// ...
};
**Alternative**: We can get part of the benefits from default arguments to constructors, and that is not uncommon in older code. However, that is less explicit, causes more arguments to be passed, and is repetitive when there is more than one constructor:
class X3 { // BAD: inexplicit, argument passing overhead
int i;
string s;
int j;
public:
X3(int ii = 666, const string& ss = "qqq", int jj = 0)
:i{ii}, s{ss}, j{jj} { } // all members are initialized to their defaults
// ...
};
##### Enforcement
* (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
##### Reason
An initialization explicitly states that initialization, rather than assignment, is done and can be more elegant and efficient. Prevents "use before set" errors.
##### Example, good
class A { // Good
string s1;
public:
A(czstring p) : s1{p} { } // GOOD: directly construct (and the C-string is explicitly named)
// ...
};
##### Example, bad
class B { // BAD
string s1;
public:
B(const char* p) { s1 = p; } // BAD: default constructor followed by assignment
// ...
};
class C { // UGLY, aka very bad
int* p;
public:
C() { cout << *p; p = new int{10}; } // accidental use before initialized
// ...
};
##### 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):
class D { // Good
string s1;
public:
D(string_view v) : s1{v} { } // GOOD: directly construct
// ...
};
### C.50: Use a factory function if you need "virtual behavior" during initialization
##### Reason
If the state of a base class object must depend on the state of a derived part of the object, we need to use a virtual function (or equivalent) while minimizing the window of opportunity to misuse an imperfectly constructed object.
##### Note
The return type of the factory should normally be `unique_ptr` by default; if some uses are shared, the caller can `move` the `unique_ptr` into a `shared_ptr`. However, if the factory author knows that all uses of the returned object will be shared uses, return `shared_ptr` and use `make_shared` in the body to save an allocation.
##### Example, bad
class B {
public:
B()
{
/* ... */
f(); // BAD: C.82: Don't call virtual functions in constructors and destructors
/* ... */
}
virtual void f() = 0;
};
##### Example
class B {
protected:
class Token {};
public:
explicit B(Token) { /* ... */ } // create an imperfectly initialized object
virtual void f() = 0;
template
static shared_ptr create() // interface for creating shared objects
{
auto p = make_shared(typename T::Token{});
p->post_initialize();
return p;
}
protected:
virtual void post_initialize() // called right after construction
{ /* ... */ f(); /* ... */ } // GOOD: virtual dispatch is safe
};
class D : public B { // some derived class
protected:
class Token {};
public:
explicit D(Token) : B{ B::Token{} } {}
void f() override { /* ... */ };
protected:
template
friend shared_ptr B::create();
};
shared_ptr p = D::create(); // creating a D object
`make_shared` requires that the constructor is public. By requiring a protected `Token` the constructor cannot be publicly called anymore, so we avoid an incompletely constructed object escaping into the wild.
By providing the factory function `create()`, we make construction (on the free store) convenient.
##### Note
Conventional factory functions allocate on the free store, rather than on the stack or in an enclosing object.
**See also**: [Discussion](#sd-factory)
### C.51: Use delegating constructors to represent common actions for all constructors of a class
##### Reason
To avoid repetition and accidental differences.
##### Example, bad
class Date { // BAD: repetitive
int d;
Month m;
int y;
public:
Date(int dd, Month mm, year yy)
:d{dd}, m{mm}, y{yy}
{ if (!valid(d, m, y)) throw Bad_date{}; }
Date(int dd, Month mm)
:d{dd}, m{mm} y{current_year()}
{ if (!valid(d, m, y)) throw Bad_date{}; }
// ...
};
The common action gets tedious to write and might accidentally not be common.
##### Example
class Date2 {
int d;
Month m;
int y;
public:
Date2(int dd, Month mm, year yy)
:d{dd}, m{mm}, y{yy}
{ if (!valid(d, m, y)) throw Bad_date{}; }
Date2(int dd, Month mm)
:Date2{dd, mm, current_year()} {}
// ...
};
**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
##### Reason
If you need those constructors for a derived class, re-implementing them is tedious and error-prone.
##### Example
`std::vector` has a lot of tricky constructors, so if I want my own `vector`, I don't want to reimplement them:
class Rec {
// ... data and lots of nice constructors ...
};
class Oper : public Rec {
using Rec::Rec;
// ... no data members ...
// ... lots of nice utility functions ...
};
##### Example, bad
struct Rec2 : public Rec {
int x;
using Rec::Rec;
};
Rec2 r {"foo", 7};
int val = r.x; // uninitialized
##### Enforcement
Make sure that every member of the derived class is initialized.
## 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&`
##### Reason
It is simple and efficient. If you want to optimize for rvalues, provide an overload that takes an `&&` (see [F.18](#rf-consume)).
##### Example
class Foo {
public:
Foo& operator=(const Foo& x)
{
// GOOD: no need to check for self-assignment (other than performance)
auto tmp = x;
swap(tmp); // see C.83
return *this;
}
// ...
};
Foo a;
Foo b;
Foo f();
a = b; // assign lvalue: copy
a = f(); // assign rvalue: potentially move
##### Note
The `swap` implementation technique offers the [strong guarantee](#Abrahams01).
##### Example
But what if you can get significantly better performance by not making a temporary copy? Consider a simple `Vector` intended for a domain where assignment of large, equal-sized `Vector`s is common. In this case, the copy of elements implied by the `swap` implementation technique could cause an order of magnitude increase in cost:
template
class Vector {
public:
Vector& operator=(const Vector&);
// ...
private:
T* elem;
int sz;
};
Vector& Vector::operator=(const Vector& a)
{
if (a.sz > sz) {
// ... use the swap technique, it can't be bettered ...
return *this;
}
// ... copy sz elements from *a.elem to elem ...
if (a.sz < sz) {
// ... destroy the surplus elements in *this and adjust size ...
}
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).
**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).
##### Enforcement
* (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) 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
##### Reason
That is the generally assumed semantics. After `x = y`, we should have `x == y`.
After a copy `x` and `y` can be independent objects (value semantics, the way non-pointer built-in types and the standard-library types work) or refer to a shared object (pointer semantics, the way pointers work).
##### Example
class X { // OK: value semantics
public:
X();
X(const X&); // copy X
void modify(); // change the value of X
// ...
~X() { delete[] p; }
private:
T* p;
int sz;
};
bool operator==(const X& a, const X& b)
{
return a.sz == b.sz && equal(a.p, a.p + a.sz, b.p, b.p + b.sz);
}
X::X(const X& a)
:p{new T[a.sz]}, sz{a.sz}
{
copy(a.p, a.p + sz, p);
}
X x;
X y = x;
if (x != y) throw Bad{};
x.modify();
if (x == y) throw Bad{}; // assume value semantics
##### Example
class X2 { // OK: pointer semantics
public:
X2();
X2(const X2&) = default; // shallow copy
~X2() = default;
void modify(); // change the pointed-to value
// ...
private:
T* p;
int sz;
};
bool operator==(const X2& a, const X2& b)
{
return a.sz == b.sz && a.p == b.p;
}
X2 x;
X2 y = x;
if (x != y) throw Bad{};
x.modify();
if (x != y) throw Bad{}; // assume pointer semantics
##### Note
Prefer value semantics unless you are building a "smart pointer". Value semantics is the simplest to reason about and what the standard-library facilities expect.
##### Enforcement
(Not enforceable)
### C.62: Make copy assignment safe for self-assignment
##### Reason
If `x = x` changes the value of `x`, people will be surprised and bad errors will occur (often including leaks).
##### Example
The standard-library containers handle self-assignment elegantly and efficiently:
std::vector v = {3, 1, 4, 1, 5, 9};
v = v;
// the value of v is still {3, 1, 4, 1, 5, 9}
##### Note
The default assignment generated from members that handle self-assignment correctly handles self-assignment.
struct Bar {
vector> v;
map m;
string s;
};
Bar b;
// ...
b = b; // correct and efficient
##### 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)).
class Foo {
string s;
int i;
public:
Foo& operator=(const Foo& a);
// ...
};
Foo& Foo::operator=(const Foo& a) // OK, but there is a cost
{
if (this == &a) return *this;
s = a.s;
i = a.i;
return *this;
}
This is obviously safe and apparently efficient.
However, what if we do one self-assignment per million assignments?
That's about a million redundant tests (but since the answer is essentially always the same, the computer's branch predictor will guess right essentially every time).
Consider:
Foo& Foo::operator=(const Foo& a) // simpler, and probably much better
{
s = a.s;
i = a.i;
return *this;
}
`std::string` is safe for self-assignment and so are `int`. All the cost is carried by the (rare) case of self-assignment.
##### Enforcement
(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&`
##### Reason
It is simple and efficient.
**See**: [The rule for copy-assignment](#rc-copy-assignment).
##### Enforcement
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
##### Reason
That is the generally assumed semantics.
After `y = std::move(x)` the value of `y` should be the value `x` had and `x` should be in a valid state.
##### Example
class X { // OK: value semantics
public:
X();
X(X&& a) noexcept; // move X
X& operator=(X&& a) noexcept; // move-assign X
void modify(); // change the value of X
// ...
~X() { delete[] p; }
private:
T* p;
int sz;
};
X::X(X&& a) noexcept
:p{a.p}, sz{a.sz} // steal representation
{
a.p = nullptr; // set to "empty"
a.sz = 0;
}
void use()
{
X x{};
// ...
X y = std::move(x);
x = X{}; // OK
} // OK: x can be destroyed
##### Note
Ideally, that moved-from should be the default value of the type.
Ensure that unless there is an exceptionally good reason not to.
However, not all types have a default value and for some types establishing the default value can be expensive.
The standard requires only that the moved-from object can be destroyed.
Often, we can easily and cheaply do better: The standard library assumes that it is possible to assign to a moved-from object.
Always leave the moved-from object in some (necessarily specified) valid state.
##### Note
Unless there is an exceptionally strong reason not to, make `x = std::move(y); y = z;` work with the conventional semantics.
##### Enforcement
(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
##### Reason
If `x = x` changes the value of `x`, people will be surprised and bad errors can occur. However, people don't usually directly write a self-assignment that turns into a move, but it can occur. However, `std::swap` is implemented using move operations so if you accidentally do `swap(a, b)` where `a` and `b` refer to the same object, failing to handle self-move could be a serious and subtle error.
##### Example
class Foo {
string s;
int i;
public:
Foo& operator=(Foo&& a) noexcept;
// ...
};
Foo& Foo::operator=(Foo&& a) noexcept // OK, but there is a cost
{
if (this == &a) return *this; // this line is redundant
s = std::move(a.s);
i = a.i;
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.
##### Note
There is no known general way of avoiding an `if (this == &a) return *this;` test for a move assignment and still getting a correct answer (i.e., after `x = x` the value of `x` is unchanged).
##### Note
The ISO standard guarantees only a "valid but unspecified" state for the standard-library containers. Apparently this has not been a problem in about 10 years of experimental and production use. Please contact the editors if you find a counter example. The rule here is more caution and insists on complete safety.
##### Example
Here is a way to move a pointer without a test (imagine it as code in the implementation a move assignment):
// move from other.ptr to this->ptr
T* temp = other.ptr;
other.ptr = nullptr;
delete ptr; // in self-move, this->ptr is also null; delete is a no-op
ptr = temp; // in self-move, the original ptr is restored
##### Enforcement
* (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`
##### Reason
A throwing move violates most people's reasonable assumptions.
A non-throwing move will be used more efficiently by standard-library and language facilities.
##### Example
template
class Vector {
public:
Vector(Vector&& a) noexcept :elem{a.elem}, sz{a.sz} { a.elem = nullptr; a.sz = 0; }
Vector& operator=(Vector&& a) noexcept {
if (&a != this) {
delete elem;
elem = a.elem; a.elem = nullptr;
sz = a.sz; a.sz = 0;
}
return *this;
}
// ...
private:
T* elem;
int sz;
};
These operations do not throw.
##### Example, bad
template
class Vector2 {
public:
Vector2(Vector2&& a) noexcept { *this = a; } // just use the copy
Vector2& operator=(Vector2&& a) noexcept { *this = a; } // just use the copy
// ...
private:
T* elem;
int sz;
};
This `Vector2` is not just inefficient, but since a vector copy requires allocation, it can throw.
##### Enforcement
(Simple) A move operation should be marked `noexcept`.
### C.67: A polymorphic class should suppress public copy/move
##### Reason
A *polymorphic class* is a class that defines or inherits at least one virtual function. It is likely that it will be used as a base class for other derived classes with polymorphic behavior. If it is accidentally passed by value, with the implicitly generated copy constructor and assignment, we risk slicing: only the base portion of a derived object will be copied, and the polymorphic behavior will be corrupted.
If the class has no data, `=delete` the copy/move functions. Otherwise, make them protected.
##### Example, bad
class B { // BAD: polymorphic base class doesn't suppress copying
public:
virtual char m() { return 'B'; }
// ... nothing about copy operations, so uses default ...
};
class D : public B {
public:
char m() override { return 'D'; }
// ...
};
void f(B& b)
{
auto b2 = b; // oops, slices the object; b2.m() will return 'B'
}
D d;
f(d);
##### Example
class B { // GOOD: polymorphic class suppresses copying
public:
B() = default;
B(const B&) = delete;
B& operator=(const B&) = delete;
virtual char m() { return 'B'; }
// ...
};
class D : public B {
public:
char m() override { return 'D'; }
// ...
};
void f(B& b)
{
auto b2 = b; // ok, compiler will detect inadvertent copying, and protest
}
D d;
f(d);
##### Note
If you need to create deep copies of polymorphic objects, use `clone()` functions: see [C.130](#rh-copy).
##### Exception
Classes that represent exception objects need both to be polymorphic and copy-constructible.
##### Enforcement
* Flag a polymorphic class with a public copy operation.
* Flag an assignment of polymorphic class objects.
## C.other: Other default operation rules
In addition to the operations for which the language offers default implementations,
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
##### Reason
The compiler is more likely to get the default semantics right and you cannot implement these functions better than the compiler.
##### Example
class Tracer {
string message;
public:
Tracer(const string& m) : message{m} { cerr << "entering " << message << '\n'; }
~Tracer() { cerr << "exiting " << message << '\n'; }
Tracer(const Tracer&) = default;
Tracer& operator=(const Tracer&) = default;
Tracer(Tracer&&) noexcept = default;
Tracer& operator=(Tracer&&) noexcept = default;
};
Because we defined the destructor, we must define the copy and move operations. The `= default` is the best and simplest way of doing that.
##### Example, bad
class Tracer2 {
string message;
public:
Tracer2(const string& m) : message{m} { cerr << "entering " << message << '\n'; }
~Tracer2() { cerr << "exiting " << message << '\n'; }
Tracer2(const Tracer2& a) : message{a.message} {}
Tracer2& operator=(const Tracer2& a) { message = a.message; return *this; }
Tracer2(Tracer2&& a) noexcept :message{a.message} {}
Tracer2& operator=(Tracer2&& a) noexcept { message = a.message; return *this; }
};
Writing out the bodies of the copy and move operations is verbose, tedious, and error-prone. A compiler does it better.
##### Enforcement
(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)
##### Reason
In a few cases, a default operation is not desirable.
##### Example
class Immortal {
public:
~Immortal() = delete; // do not allow destruction
// ...
};
void use()
{
Immortal ugh; // error: ugh cannot be destroyed
Immortal* p = new Immortal{};
delete p; // error: cannot destroy *p
}
##### Example
A `unique_ptr` can be moved, but not copied. To achieve that its copy operations are deleted. To avoid copying it is necessary to `=delete` its copy operations from lvalues:
template> class unique_ptr {
public:
// ...
constexpr unique_ptr() noexcept;
explicit unique_ptr(pointer p) noexcept;
// ...
unique_ptr(unique_ptr&& u) noexcept; // move constructor
// ...
unique_ptr(const unique_ptr&) = delete; // disable copy from lvalue
// ...
};
unique_ptr make(); // make "something" and return it by moving
void f()
{
unique_ptr pi {};
auto pi2 {pi}; // error: no move constructor from lvalue
auto pi3 {make()}; // OK, move: the result of make() is an rvalue
}
Note that deleted functions should be public.
##### Enforcement
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
##### Reason
The function called will be that of the object constructed so far, rather than a possibly overriding function in a derived class.
This can be most confusing.
Worse, a direct or indirect call to an unimplemented pure virtual function from a constructor or destructor results in undefined behavior.
##### Example, bad
class Base {
public:
virtual void f() = 0; // not implemented
virtual void g(); // implemented with Base version
virtual void h(); // implemented with Base version
virtual ~Base(); // implemented with Base version
};
class Derived : public Base {
public:
void g() override; // provide Derived implementation
void h() final; // provide Derived implementation
Derived()
{
// BAD: attempt to call an unimplemented virtual function
f();
// BAD: will call Derived::g, not dispatch further virtually
g();
// GOOD: explicitly state intent to call only the visible version
Derived::g();
// ok, no qualification needed, h is final
h();
}
};
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.
##### Note
There is nothing inherently wrong with calling virtual functions from constructors and destructors.
The semantics of such calls is type safe.
However, experience shows that such calls are rarely needed, easily confuse maintainers, and become a source of errors when used by novices.
##### Enforcement
* Flag calls of virtual functions from constructors and destructors.
### 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).
##### Example, good
class Foo {
public:
void swap(Foo& rhs) noexcept
{
m1.swap(rhs.m1);
std::swap(m2, rhs.m2);
}
private:
Bar m1;
int m2;
};
Providing a non-member `swap` function in the same namespace as your type for callers' convenience.
void swap(Foo& a, Foo& b)
{
a.swap(b);
}
##### Enforcement
* 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
##### Reason
`swap` is widely used in ways that are assumed never to fail and programs cannot easily be written to work correctly in the presence of a failing `swap`. The standard-library containers and algorithms will not work correctly if a swap of an element type fails.
##### Example, bad
void swap(My_vector& x, My_vector& y)
{
auto tmp = x; // copy elements
x = y;
y = tmp;
}
This is not just slow, but if a memory allocation occurs for the elements in `tmp`, this `swap` could throw and would make STL algorithms fail if used with them.
##### Enforcement
(Simple) When a class has a `swap` member function, it should be declared `noexcept`.
### C.85: Make `swap` `noexcept`
##### Reason
[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`
##### Reason
Asymmetric treatment of operands is surprising and a source of errors where conversions are possible.
`==` is a fundamental operation and programmers should be able to use it without fear of failure.
##### Example
struct X {
string name;
int number;
};
bool operator==(const X& a, const X& b) noexcept {
return a.name == b.name && a.number == b.number;
}
##### Example, bad
class B {
string name;
int number;
bool operator==(const B& a) const {
return name == a.name && number == a.number;
}
// ...
};
`B`'s comparison accepts conversions for its second operand, but not its first.
##### Note
If a class has a failure state, like `double`'s `NaN`, there is a temptation to make a comparison against the failure state throw.
The alternative is to make two failure states compare equal and any valid state compare false against the failure state.
##### Note
This rule applies to all the usual comparison operators: `!=`, `<`, `<=`, `>`, and `>=`.
##### Enforcement
* 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
##### Reason
It is really hard to write a foolproof and useful `==` for a hierarchy.
##### Example, bad
class B {
string name;
int number;
public:
virtual bool operator==(const B& a) const
{
return name == a.name && number == a.number;
}
// ...
};
`B`'s comparison accepts conversions for its second operand, but not its first.
class D : public B {
char character;
public:
virtual bool operator==(const D& a) const
{
return B::operator==(a) && character == a.character;
}
// ...
};
B b = ...
D d = ...
b == d; // compares name and number, ignores d's character
d == b; // compares name and number, ignores d's character
D d2;
d == d2; // compares name, number, and character
B& b2 = d2;
b2 == d; // compares name and number, ignores d2's and d's character
Of course there are ways of making `==` work in a hierarchy, but the naive approaches do not scale.
##### Note
This rule applies to all the usual comparison operators: `!=`, `<`, `<=`, `>`, `>=`, and `<=>`.
##### Enforcement
* Flag a virtual `operator==()`; same for other comparison operators: `!=`, `<`, `<=`, `>`, `>=`, and `<=>`.
### C.89: Make a `hash` `noexcept`
##### Reason
Users of hashed containers use hash indirectly and don't expect simple access to throw.
It's a standard-library requirement.
##### Example, bad
template<>
struct hash { // thoroughly bad hash specialization
using result_type = size_t;
using argument_type = My_type;
size_t operator()(const My_type & x) const
{
size_t xs = x.s.size();
if (xs < 4) throw Bad_My_type{}; // "Nobody expects the Spanish inquisition!"
return hash()(x.s.size()) ^ trim(x.s);
}
};
int main()
{
unordered_map m;
My_type mt{ "asdfg" };
m[mt] = 7;
cout << m[My_type{ "asdfg" }] << '\n';
}
If you have to define a `hash` specialization, try simply to let it combine standard-library `hash` specializations with `^` (xor).
That tends to work better than "cleverness" for non-specialists.
##### Enforcement
* Flag throwing `hash`es.
### 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.
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
struct base {
virtual void update() = 0;
std::shared_ptr sp;
};
struct derived : public base {
void update() override {}
};
##### Example, bad
void init(derived& a)
{
memset(&a, 0, sizeof(derived));
}
This is type-unsafe and overwrites the vtable.
##### Example, bad
void copy(derived& a, derived& b)
{
memcpy(&a, &b, sizeof(derived));
}
This is also type-unsafe and overwrites the vtable.
##### Enforcement
* Flag passing a non-trivially-copyable type to `memset` or `memcpy`.
## 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.109: If a resource handle has pointer semantics, provide `*` and `->`](#rcon-ptr)
**See also**: [Resources](#s-resource)
### C.100: Follow the STL when defining a container
##### Reason
The STL containers are familiar to most C++ programmers and a fundamentally sound design.
##### Note
There are of course other fundamentally sound design styles and sometimes reasons to depart from
the style of the standard library, but in the absence of a solid reason to differ, it is simpler
and easier for both implementers and users to follow the standard.
In particular, `std::vector` and `std::map` provide useful relatively simple models.
##### Example
// simplified (e.g., no allocators):
template
class Sorted_vector {
using value_type = T;
// ... iterator types ...
Sorted_vector() = default;
Sorted_vector(initializer_list); // initializer-list constructor: sort and store
Sorted_vector(const Sorted_vector&) = default;
Sorted_vector(Sorted_vector&&) noexcept = default;
Sorted_vector& operator=(const Sorted_vector&) = default; // copy assignment
Sorted_vector& operator=(Sorted_vector&&) noexcept = default; // move assignment
~Sorted_vector() = default;
Sorted_vector(const std::vector& v); // store and sort
Sorted_vector(std::vector&& v); // sort and "steal representation"
const T& operator[](int i) const { return rep[i]; }
// no non-const direct access to preserve order
void push_back(const T&); // insert in the right place (not necessarily at back)
void push_back(T&&); // insert in the right place (not necessarily at back)
// ... cbegin(), cend() ...
private:
std::vector rep; // use a std::vector to hold elements
};
template bool operator==(const Sorted_vector&, const Sorted_vector&);
template bool operator!=(const Sorted_vector&, const Sorted_vector&);
// ...
Here, the STL style is followed, but incompletely.
That's not uncommon.
Provide only as much functionality as makes sense for a specific container.
The key is to define the conventional constructors, assignments, destructors, and iterators
(as meaningful for the specific container) with their conventional semantics.
From that base, the container can be expanded as needed.
Here, special constructors from `std::vector` were added.
##### Enforcement
???
### C.101: Give a container value semantics
##### Reason
Regular objects are simpler to think and reason about than irregular ones.
Familiarity.
##### Note
If meaningful, make a container `Regular` (the concept).
In particular, ensure that an object compares equal to its copy.
##### Example
void f(const Sorted_vector& v)
{
Sorted_vector v2 {v};
if (v != v2)
cout << "Behavior against reason and logic.\n";
// ...
}
##### Enforcement
???
### C.102: Give a container move operations
##### Reason
Containers tend to get large; without a move constructor and a copy constructor an object can be
expensive to move around, thus tempting people to pass pointers to it around and getting into
resource management problems.
##### Example
Sorted_vector read_sorted(istream& is)
{
vector v;
cin >> v; // assume we have a read operation for vectors
Sorted_vector sv = v; // sorts
return sv;
}
A user can reasonably assume that returning a standard-like container is cheap.
##### Enforcement
???
### C.103: Give a container an initializer list constructor
##### Reason
People expect to be able to initialize a container with a set of values.
Familiarity.
##### Example
Sorted_vector sv {1, 3, -1, 7, 0, 0}; // Sorted_vector sorts elements as needed
##### Enforcement
???
### C.104: Give a container a default constructor that sets it to empty
##### Reason
To make it `Regular`.
##### Example
vector> vs(100); // 100 Sorted_sequences each with the value ""
##### Enforcement
???
### C.109: If a resource handle has pointer semantics, provide `*` and `->`
##### Reason
That's what is expected from pointers.
Familiarity.
##### Example
???
##### Enforcement
???
## 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)).
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)
## 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.
There are two major uses for hierarchies, often named implementation inheritance and interface 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)
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)
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.120: Use class hierarchies to represent concepts with inherent hierarchical structure (only)
##### Reason
Direct representation of ideas in code eases comprehension and maintenance. Make sure the idea represented in the base class exactly matches all derived types and there is not a better way to express it than using the tight coupling of inheritance.
Do *not* use inheritance when simply having a data member will do. Usually this means that the derived type needs to override a base virtual function or needs access to a protected member.
##### Example
class DrawableUIElement {
public:
virtual void render() const = 0;
// ...
};
class AbstractButton : public DrawableUIElement {
public:
virtual void onClick() = 0;
// ...
};
class PushButton : public AbstractButton {
void render() const override;
void onClick() override;
// ...
};
class Checkbox : public AbstractButton {
// ...
};
##### Example, bad
Do *not* represent non-hierarchical domain concepts as class hierarchies.
template
class Container {
public:
// list operations:
virtual T& get() = 0;
virtual void put(T&) = 0;
virtual void insert(Position) = 0;
// ...
// vector operations:
virtual T& operator[](int) = 0;
virtual void sort() = 0;
// ...
// tree operations:
virtual void balance() = 0;
// ...
};
Here most overriding classes cannot implement most of the functions required in the interface well.
Thus the base class becomes an implementation burden.
Furthermore, the user of `Container` cannot rely on the member functions actually performing meaningful operations reasonably efficiently;
it might throw an exception instead.
Thus users have to resort to run-time checking and/or
not using this (over)general interface in favor of a particular interface found by a run-time type inquiry (e.g., a `dynamic_cast`).
##### Enforcement
* 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
##### Reason
A class is more stable (less brittle) if it does not contain data.
Interfaces should normally be composed entirely of public pure virtual functions and a default/empty virtual destructor.
##### Example
class My_interface {
public:
// ... only pure virtual functions here ...
virtual ~My_interface() {} // or =default
};
##### Example, bad
class Goof {
public:
// ... only pure virtual functions here ...
// no virtual destructor
};
class Derived : public Goof {
string s;
// ...
};
void use()
{
unique_ptr p {new Derived{"here we go"}};
f(p.get()); // use Derived through the Goof interface
g(p.get()); // use Derived through the Goof interface
} // leak
The `Derived` is `delete`d through its `Goof` interface, so its `string` is leaked.
Give `Goof` a virtual destructor and all is well.
##### Enforcement
* 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
##### Reason
Such as on an ABI (link) boundary.
##### Example
struct Device {
virtual ~Device() = default;
virtual void write(span outbuf) = 0;
virtual void read(span inbuf) = 0;
};
class D1 : public Device {
// ... data ...
void write(span outbuf) override;
void read(span inbuf) override;
};
class D2 : public Device {
// ... different data ...
void write(span outbuf) override;
void read(span inbuf) override;
};
A user can now use `D1`s and `D2`s interchangeably through the interface provided by `Device`.
Furthermore, we can update `D1` and `D2` in ways that are not binary compatible with older versions as long as all access goes through `Device`.
##### Enforcement
???
## C.hierclass: Designing classes in a hierarchy:
### C.126: An abstract class typically doesn't need a user-written constructor
##### Reason
An abstract class typically does not have any data for a constructor to initialize.
##### Example
class Shape {
public:
// no user-written constructor needed in abstract base class
virtual Point center() const = 0; // pure virtual
virtual void move(Point to) = 0;
// ... more pure virtual functions ...
virtual ~Shape() {} // destructor
};
class Circle : public Shape {
public:
Circle(Point p, int rad); // constructor in derived class
Point center() const override { return x; }
};
##### Exception
* A base class constructor that does work, such as registering an object somewhere, might need a constructor.
* In extremely rare cases, you might find it reasonable for an abstract class to have a bit of data shared by all derived classes
(e.g., use statistics data, debug information, etc.); such classes tend to have constructors. But be warned: Such classes also tend to be prone to requiring virtual inheritance.
##### Enforcement
Flag abstract classes with constructors.
### 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).
##### Example, bad
struct B {
virtual int f() = 0;
// ... no user-written destructor, defaults to public non-virtual ...
};
// bad: derived from a class without a virtual destructor
struct D : B {
string s {"default"};
// ...
};
void use()
{
unique_ptr p = make_unique();
// ...
} // undefined behavior, might call B::~B only and leak the string
##### Note
There are people who don't follow this rule because they plan to use a class only through a `shared_ptr`: `std::shared_ptr p = std::make_shared(args);` Here, the shared pointer will take care of deletion, so no leak will occur from an inappropriate `delete` of the base. People who do this consistently can get a false positive, but the rule is important -- what if one was allocated using `make_unique`? It's not safe unless the author of `B` ensures that it can never be misused, such as by making all constructors private and providing a factory function to enforce the allocation with `make_shared`.
##### Enforcement
* 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`
##### Reason
Readability.
Detection of mistakes.
Writing explicit `virtual`, `override`, or `final` is self-documenting and enables the compiler to catch mismatch of types and/or names between base and derived classes. However, writing more than one of these three is both redundant and a potential source of errors.
It's simple and clear:
* `virtual` means exactly and only "this is a new virtual function."
* `override` means exactly and only "this is a non-final overrider."
* `final` means exactly and only "this is a final overrider."
##### Example, bad
struct B {
void f1(int);
virtual void f2(int) const;
virtual void f3(int);
// ...
};
struct D : B {
void f1(int); // bad (hope for a warning): D::f1() hides B::f1()
void f2(int) const; // bad (but conventional and valid): no explicit override
void f3(double); // bad (hope for a warning): D::f3() hides B::f3()
// ...
};
##### Example, good
struct Better : B {
void f1(int) override; // error (caught): Better::f1() hides B::f1()
void f2(int) const override;
void f3(double) override; // error (caught): Better::f3() hides B::f3()
// ...
};
#### Discussion
We want to eliminate two particular classes of errors:
* **implicit virtual**: the programmer intended the function to be implicitly virtual and it is (but readers of the code can't tell); or the programmer intended the function to be implicitly virtual but it isn't (e.g., because of a subtle parameter list mismatch); or the programmer did not intend the function to be virtual but it is (because it happens to have the same signature as a virtual in the base class)
* **implicit override**: the programmer intended the function to be implicitly an overrider and it is (but readers of the code can't tell); or the programmer intended the function to be implicitly an overrider but it isn't (e.g., because of a subtle parameter list mismatch); or the programmer did not intend the function to be an overrider but it is (because it happens to have the same signature as a virtual in the base class -- note this problem arises whether or not the function is explicitly declared virtual, because the programmer might have intended to create either a new virtual function or a new non-virtual function)
Note: On a class defined as `final`, each individual virtual function should use either `override` or `final`; there is no semantic difference in this case.
Note: Use `final` on functions sparingly. It does not necessarily lead to optimization, and it precludes further overriding.
##### Enforcement
* Compare virtual function names in base and derived classes and flag uses of the same name that do not override.
* 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
##### Reason
Implementation details in an interface make the interface brittle;
that is, make its users vulnerable to having to recompile after changes in the implementation.
Data in a base class increases the complexity of implementing the base and can lead to replication of code.
##### Note
Definition:
* interface inheritance is the use of inheritance to separate users from implementations,
in particular to allow derived classes to be added and changed without affecting the users of base classes.
* 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).
In early OOP (e.g., in the 1980s and 1990s), implementation inheritance and interface inheritance were often mixed
and bad habits die hard.
Even now, mixtures are not uncommon in old code bases and in old-style teaching material.
The importance of keeping the two kinds of inheritance increases
* with the size of a hierarchy (e.g., dozens of derived classes),
* with the length of time the hierarchy is used (e.g., decades), and
* with the number of distinct organizations in which a hierarchy is used
(e.g., it can be difficult to distribute an update to a base class)
##### Example, bad
class Shape { // BAD, mixed interface and implementation
public:
Shape();
Shape(Point ce = {0, 0}, Color co = none): cent{ce}, col {co} { /* ... */}
Point center() const { return cent; }
Color color() const { return col; }
virtual void rotate(int) = 0;
virtual void move(Point p) { cent = p; redraw(); }
virtual void redraw();
// ...
private:
Point cent;
Color col;
};
class Circle : public Shape {
public:
Circle(Point c, int r) : Shape{c}, rad{r} { /* ... */ }
// ...
private:
int rad;
};
class Triangle : public Shape {
public:
Triangle(Point p1, Point p2, Point p3); // calculate center
// ...
};
Problems:
* As the hierarchy grows and more data is added to `Shape`, the constructors get harder to write and maintain.
* Why calculate the center for the `Triangle`? We might never use it.
* Add a data member to `Shape` (e.g., drawing style or canvas)
and all classes derived from `Shape` and all code using `Shape` will need to be reviewed, possibly changed, and probably recompiled.
The implementation of `Shape::move()` is an example of implementation inheritance:
we have defined `move()` once and for all, for all derived classes.
The more code there is in such base class member function implementations and the more data is shared by placing it in the base,
the more benefits we gain - and the less stable the hierarchy is.
##### Example
This Shape hierarchy can be rewritten using interface inheritance:
class Shape { // pure interface
public:
virtual Point center() const = 0;
virtual Color color() const = 0;
virtual void rotate(int) = 0;
virtual void move(Point p) = 0;
virtual void redraw() = 0;
// ...
};
Note that a pure interface rarely has constructors: there is nothing to construct.
class Circle : public Shape {
public:
Circle(Point c, int r, Color c) : cent{c}, rad{r}, col{c} { /* ... */ }
Point center() const override { return cent; }
Color color() const override { return col; }
// ...
private:
Point cent;
int rad;
Color col;
};
The interface is now less brittle, but there is more work in implementing the member functions.
For example, `center` has to be implemented by every class derived from `Shape`.
##### Example, dual hierarchy
How can we gain the benefit of stable hierarchies from interface hierarchies and the benefit of implementation reuse from implementation inheritance?
One popular technique is dual hierarchies.
There are many ways of implementing the idea of dual hierarchies; here, we use a multiple-inheritance variant.
First we devise a hierarchy of interface classes:
class Shape { // pure interface
public:
virtual Point center() const = 0;
virtual Color color() const = 0;
virtual void rotate(int) = 0;
virtual void move(Point p) = 0;
virtual void redraw() = 0;
// ...
};
class Circle : public virtual Shape { // pure interface
public:
virtual int radius() = 0;
// ...
};
To make this interface useful, we must provide its implementation classes (here, named equivalently, but in the `Impl` namespace):
class Impl::Shape : public virtual ::Shape { // implementation
public:
// constructors, destructor
// ...
Point center() const override { /* ... */ }
Color color() const override { /* ... */ }
void rotate(int) override { /* ... */ }
void move(Point p) override { /* ... */ }
void redraw() override { /* ... */ }
// ...
};
Now `Shape` is a poor example of a class with an implementation,
but bear with us because this is just a simple example of a technique aimed at more complex hierarchies.
class Impl::Circle : public virtual ::Circle, public Impl::Shape { // implementation
public:
// constructors, destructor
int radius() override { /* ... */ }
// ...
};
And we could extend the hierarchies by adding a Smiley class (:-)):
class Smiley : public virtual Circle { // pure interface
public:
// ...
};
class Impl::Smiley : public virtual ::Smiley, public Impl::Circle { // implementation
public:
// constructors, destructor
// ...
}
There are now two hierarchies:
* interface: Smiley -> Circle -> Shape
* implementation: Impl::Smiley -> Impl::Circle -> Impl::Shape
Since each implementation is derived from its interface as well as its implementation base class we get a lattice (DAG):
Smiley -> Circle -> Shape
^ ^ ^
| | |
Impl::Smiley -> Impl::Circle -> Impl::Shape
As mentioned, this is just one way to construct a dual hierarchy.
The implementation hierarchy can be used directly, rather than through the abstract interface.
void work_with_shape(Shape&);
int user()
{
Impl::Smiley my_smiley{ /* args */ }; // create concrete shape
// ...
my_smiley.some_member(); // use implementation class directly
// ...
work_with_shape(my_smiley); // use implementation through abstract interface
// ...
}
This can be useful when the implementation class has members that are not offered in the abstract interface
or if direct use of a member offers optimization opportunities (e.g., if an implementation member function is `final`).
##### Note
Another (related) technique for separating interface and implementation is [Pimpl](#ri-pimpl).
##### Note
There is often a choice between offering common functionality as (implemented) base class functions and freestanding functions
(in an implementation namespace).
Base classes give a shorter notation and easier access to shared data (in the base)
at the cost of the functionality being available only to users of the hierarchy.
##### Enforcement
* Flag a derived to base conversion to a base with both data and virtual functions
(except for calls from a derived class member to a base class member)
* ???
### 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).
##### Example
class B {
public:
B() = default;
virtual ~B() = default;
virtual gsl::owner clone() const = 0;
protected:
B(const B&) = default;
B& operator=(const B&) = default;
B(B&&) noexcept = default;
B& operator=(B&&) noexcept = default;
// ...
};
class D : public B {
public:
gsl::owner clone() const override
{
return new D{*this};
};
};
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
##### Reason
A trivial getter or setter adds no semantic value; the data item could just as well be `public`.
##### Example
class Point { // Bad: verbose
int x;
int y;
public:
Point(int xx, int yy) : x{xx}, y{yy} { }
int get_x() const { return x; }
void set_x(int xx) { x = xx; }
int get_y() const { return y; }
void set_y(int yy) { y = yy; }
// no behavioral member functions
};
Consider making such a class a `struct` -- that is, a behaviorless bunch of variables, all public data and no member functions.
struct Point {
int x {0};
int y {0};
};
Note that we can put default initializers on data members: [C.49: Prefer initialization to assignment in constructors](#rc-initialize).
##### Note
The key to this rule is whether the semantics of the getter/setter are trivial. While it is not a complete definition of "trivial", consider whether there would be any difference beyond syntax if the getter/setter was a public data member instead. Examples of non-trivial semantics would be: maintaining a class invariant or converting between an internal type and an interface type.
##### Enforcement
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
##### Reason
Redundant `virtual` increases run-time and object-code size.
A virtual function can be overridden and is thus open to mistakes in a derived class.
A virtual function ensures code replication in a templated hierarchy.
##### Example, bad
template
class Vector {
public:
// ...
virtual int size() const { return sz; } // bad: what good could a derived class do?
private:
T* elem; // the elements
int sz; // number of elements
};
This kind of "vector" isn't meant to be used as a base class at all.
##### Enforcement
* 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
**Alternative formulation**: Make member data `public` or (preferably) `private`.
##### Reason
`protected` data is a source of complexity and errors.
`protected` data complicates the statement of invariants.
`protected` data inherently violates the guidance against putting data in base classes, which usually leads to having to deal with virtual inheritance as well.
##### Example, bad
class Shape {
public:
// ... interface functions ...
protected:
// data for use in derived classes:
Color fill_color;
Color edge_color;
Style st;
};
Now it is up to every derived `Shape` to manipulate the protected data correctly.
This has been popular, but also a major source of maintenance problems.
In a large class hierarchy, the consistent use of protected data is hard to maintain because there can be a lot of code,
spread over a lot of classes.
The set of classes that can touch that data is open: anyone can derive a new class and start manipulating the protected data.
Often, it is not possible to examine the complete set of classes, so any change to the representation of the class becomes infeasible.
There is no enforced invariant for the protected data; it is much like a set of global variables.
The protected data has de facto become global to a large body of code.
##### Note
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).
##### Note
Protected member function can be just fine.
##### Enforcement
Flag classes with `protected` data.
### C.134: Ensure all non-`const` data members have the same access level
##### Reason
Prevention of logical confusion leading to errors.
If the non-`const` data members don't have the same access level, the type is confused about what it's trying to do.
Is it a type that maintains an invariant or simply a collection of values?
##### Discussion
The core question is: What code is responsible for maintaining a meaningful/correct value for that variable?
There are exactly two kinds of data members:
* A: Ones that don't participate in the object's invariant. Any combination of values for these members is valid.
* B: Ones that do participate in the object's invariant. Not every combination of values is meaningful (else there'd be no invariant). Therefore all code that has write access to these variables must know about the invariant, know the semantics, and know (and actively implement and enforce) the rules for keeping the values correct.
Data members in category A should just be `public` (or, more rarely, `protected` if you only want derived classes to see them). They don't need encapsulation. All code in the system might as well see and manipulate them.
Data members in category B should be `private` or `const`. This is because encapsulation is important. To make them non-`private` and non-`const` would mean that the object can't control its own state: An unbounded amount of code beyond the class would need to know about the invariant and participate in maintaining it accurately -- if these data members were `public`, that would be all calling code that uses the object; if they were `protected`, it would be all the code in current and future derived classes. This leads to brittle and tightly coupled code that quickly becomes a nightmare to maintain. Any code that inadvertently sets the data members to an invalid or unexpected combination of values would corrupt the object and all subsequent uses of the object.
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)
* *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
Occasionally classes will mix A and B, usually for debug reasons. An encapsulated object might contain something like non-`const` debug instrumentation that isn't part of the invariant and so falls into category A -- it isn't really part of the object's value or meaningful observable state either. In that case, the A parts should be treated as A's (made `public`, or in rarer cases `protected` if they should be visible only to derived classes) and the B parts should still be treated like B's (`private` or `const`).
##### Enforcement
Flag any class that has non-`const` data members with different access levels.
### C.135: Use multiple inheritance to represent multiple distinct interfaces
##### Reason
Not all classes will necessarily support all interfaces, and not all callers will necessarily want to deal with all operations.
Especially to break apart monolithic interfaces into "aspects" of behavior supported by a given derived class.
##### Example
class iostream : public istream, public ostream { // very simplified
// ...
};
`istream` provides the interface to input operations; `ostream` provides the interface to output operations.
`iostream` provides the union of the `istream` and `ostream` interfaces and the synchronization needed to allow both on a single stream.
##### Note
This is a very common use of inheritance because the need for multiple different interfaces to an implementation is common
and such interfaces are often not easily or naturally organized into a single-rooted hierarchy.
##### Note
Such interfaces are typically abstract classes.
##### Enforcement
???
### C.136: Use multiple inheritance to represent the union of implementation attributes
##### Reason
Some forms of mixins have state and often operations on that state.
If the operations are virtual the use of inheritance is necessary, if not using inheritance can avoid boilerplate and forwarding.
##### Example
class iostream : public istream, public ostream { // very simplified
// ...
};
`istream` provides the interface to input operations (and some data); `ostream` provides the interface to output operations (and some data).
`iostream` provides the union of the `istream` and `ostream` interfaces and the synchronization needed to allow both on a single stream.
##### Note
This is a relatively rare use because implementation can often be organized into a single-rooted hierarchy.
##### Example
Sometimes, an "implementation attribute" is more like a "mixin" that determines the behavior of an implementation and injects
members to enable the implementation of the policies it requires.
For example, see `std::enable_shared_from_this`
or various bases from boost.intrusive (e.g. `list_base_hook` or `intrusive_ref_counter`).
##### Enforcement
???
### C.137: Use `virtual` bases to avoid overly general base classes
##### Reason
Allow separation of shared data and interface.
To avoid all shared data to being put into an ultimate base class.
##### Example
struct Interface {
virtual void f();
virtual int g();
// ... no data here ...
};
class Utility { // with data
void utility1();
virtual void utility2(); // customization point
public:
int x;
int y;
};
class Derive1 : public Interface, virtual protected Utility {
// override Interface functions
// Maybe override Utility virtual functions
// ...
};
class Derive2 : public Interface, virtual protected Utility {
// override Interface functions
// Maybe override Utility virtual functions
// ...
};
Factoring out `Utility` makes sense if many derived classes share significant "implementation details."
##### 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).
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
Often, linearization of a hierarchy is a better solution.
##### Enforcement
Flag mixed interface and implementation hierarchies.
### C.138: Create an overload set for a derived class and its bases with `using`
##### Reason
Without a using declaration, member functions in the derived class hide the entire inherited overload sets.
##### Example, bad
#include
class B {
public:
virtual int f(int i) { std::cout << "f(int): "; return i; }
virtual double f(double d) { std::cout << "f(double): "; return d; }
virtual ~B() = default;
};
class D: public B {
public:
int f(int i) override { std::cout << "f(int): "; return i + 1; }
};
int main()
{
D d;
std::cout << d.f(2) << '\n'; // prints "f(int): 3"
std::cout << d.f(2.3) << '\n'; // prints "f(int): 3"
}
##### Example, good
class D: public B {
public:
int f(int i) override { std::cout << "f(int): "; return i + 1; }
using B::f; // exposes f(double)
};
##### Note
This issue affects both virtual and non-virtual member functions
For variadic bases, C++17 introduced a variadic form of the using-declaration,
template
struct Overloader : Ts... {
using Ts::operator()...; // exposes operator() from every base
};
##### Enforcement
Diagnose name hiding
### C.139: Use `final` on classes sparingly
##### Reason
Capping a hierarchy with `final` classes is rarely needed for logical reasons and can be damaging to the extensibility of a hierarchy.
##### Example, bad
class Widget { /* ... */ };
// nobody will ever want to improve My_widget (or so you thought)
class My_widget final : public Widget { /* ... */ };
class My_improved_widget : public My_widget { /* ... */ }; // error: can't do that
##### Note
Not every class is meant to be a base class.
Most standard-library classes are examples of that (e.g., `std::vector` and `std::string` are not designed to be derived from).
This rule is about using `final` on classes with virtual functions meant to be interfaces for a class hierarchy.
##### Note
Claims of performance improvements from `final` should be substantiated.
Too often, such claims are based on conjecture or experience with other languages.
There are examples where `final` can be important for both logical and performance reasons.
One example is a performance-critical AST hierarchy in a compiler or language analysis tool.
New derived classes are not added every year and only by library implementers.
However, misuses are (or at least have been) far more common.
##### Enforcement
Flag uses of `final` on classes.
### C.140: Do not provide different default arguments for a virtual function and an overrider
##### Reason
That can cause confusion: An overrider does not inherit default arguments.
##### Example, bad
class Base {
public:
virtual int multiply(int value, int factor = 2) = 0;
virtual ~Base() = default;
};
class Derived : public Base {
public:
int multiply(int value, int factor = 10) override;
};
Derived d;
Base& b = d;
b.multiply(10); // these two calls will call the same function but
d.multiply(10); // with different arguments and so different results
##### Enforcement
Flag default arguments on virtual functions if they differ between base and derived declarations.
## C.hier-access: Accessing objects in a hierarchy
### C.145: Access polymorphic objects through pointers and references
##### Reason
If you have a class with a virtual function, you don't (in general) know which class provided the function to be used.
##### Example
struct B { int a; virtual int f(); virtual ~B() = default };
struct D : B { int b; int f() override; };
void use(B b)
{
D d;
B b2 = d; // slice
B b3 = b;
}
void use2()
{
D d;
use(d); // slice
}
Both `d`s are sliced.
##### Exception
You can safely access a named polymorphic object in the scope of its definition, just don't slice it.
void use3()
{
D d;
d.f(); // OK
}
##### See also
[A polymorphic class should suppress copying](#rc-copy-virtual)
##### Enforcement
Flag all slicing.
### C.146: Use `dynamic_cast` where class hierarchy navigation is unavoidable
##### Reason
`dynamic_cast` is checked at run time.
##### Example
struct B { // an interface
virtual void f();
virtual void g();
virtual ~B();
};
struct D : B { // a wider interface
void f() override;
virtual void h();
};
void user(B* pb)
{
if (D* pd = dynamic_cast(pb)) {
// ... use D's interface ...
}
else {
// ... make do with B's interface ...
}
}
Use of the other casts can violate type safety and cause the program to access a variable that is actually of type `X` to be accessed as if it were of an unrelated type `Z`:
void user2(B* pb) // bad
{
D* pd = static_cast(pb); // I know that pb really points to a D; trust me
// ... use D's interface ...
}
void user3(B* pb) // unsafe
{
if (some_condition) {
D* pd = static_cast(pb); // I know that pb really points to a D; trust me
// ... use D's interface ...
}
else {
// ... make do with B's interface ...
}
}
void f()
{
B b;
user(&b); // OK
user2(&b); // bad error
user3(&b); // OK *if* the programmer got the some_condition check right
}
##### Note
Like other casts, `dynamic_cast` is overused.
[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.
##### Note
Some people use `dynamic_cast` where a `typeid` would have been more appropriate;
`dynamic_cast` is a general "is kind of" operation for discovering the best interface to an object,
whereas `typeid` is a "give me the exact type of this object" operation to discover the actual type of an object.
The latter is an inherently simpler operation that ought to be faster.
The latter (`typeid`) is easily hand-crafted if necessary (e.g., if working on a system where RTTI is -- for some reason -- prohibited),
the former (`dynamic_cast`) is far harder to implement correctly in general.
Consider:
struct B {
const char* name {"B"};
// if pb1->id() == pb2->id() *pb1 is the same type as *pb2
virtual const char* id() const { return name; }
// ...
};
struct D : B {
const char* name {"D"};
const char* id() const override { return name; }
// ...
};
void use()
{
B* pb1 = new B;
B* pb2 = new D;
cout << pb1->id(); // "B"
cout << pb2->id(); // "D"
if (pb2->id() == "D") { // looks innocent
D* pd = static_cast(pb2);
// ...
}
// ...
}
The result of `pb2->id() == "D"` is actually implementation defined.
We added it to warn of the dangers of home-brew RTTI.
This code might work as expected for years, just to fail on a new machine, new compiler, or a new linker that does not unify character literals.
If you implement your own RTTI, be careful.
##### Exception
If your implementation provided a really slow `dynamic_cast`, you might have to use a workaround.
However, all workarounds that cannot be statically resolved involve explicit casting (typically `static_cast`) and are error-prone.
You will basically be crafting your own special-purpose `dynamic_cast`.
So, first make sure that your `dynamic_cast` really is as slow as you think it is (there are a fair number of unsupported rumors about)
and that your use of `dynamic_cast` is really performance critical.
We are of the opinion that current implementations of `dynamic_cast` are unnecessarily slow.
For example, under suitable conditions, it is possible to perform a `dynamic_cast` in [fast constant time](https://www.stroustrup.com/fast_dynamic_casting.pdf).
However, compatibility makes changes difficult even if all agree that an effort to optimize is worthwhile.
In very rare cases, if you have measured that the `dynamic_cast` overhead is material, you have other means to statically guarantee that a downcast will succeed (e.g., you are using CRTP carefully), and there is no virtual inheritance involved, consider tactically resorting `static_cast` with a prominent comment and disclaimer summarizing this paragraph and that human attention is needed under maintenance because the type system can't verify correctness. Even so, in our experience such "I know what I'm doing" situations are still a known bug source.
##### Exception
Consider:
template
class Dx : B {
// ...
};
##### 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).
### C.147: Use `dynamic_cast` to a reference type when failure to find the required class is considered an error
##### Reason
Casting to a reference expresses that you intend to end up with a valid object, so the cast must succeed. `dynamic_cast` will then throw if it does not succeed.
##### Example
std::string f(Base& b)
{
return dynamic_cast(b).to_string();
}
##### Enforcement
???
### 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.
##### Example
The example below describes the `add` function of a `Shape_owner` that takes ownership of constructed `Shape` objects. The objects are also sorted into views, according to their geometric attributes.
In this example, `Shape` does not inherit from `Geometric_attributes`. Only its subclasses do.
void add(Shape* const item)
{
// Ownership is always taken
owned_shapes.emplace_back(item);
// Check the Geometric_attributes and add the shape to none/one/some/all of the views
if (auto even = dynamic_cast(item))
{
view_of_evens.emplace_back(even);
}
if (auto trisym = dynamic_cast(item))
{
view_of_trisyms.emplace_back(trisym);
}
}
##### Notes
A failure to find the required class will cause `dynamic_cast` to return a null value, and de-referencing a null-valued pointer will lead to undefined behavior.
Therefore the result of the `dynamic_cast` should always be treated as if it might contain a null value, and tested.
##### Enforcement
* (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`
##### Reason
Avoid resource leaks.
##### Example
void use(int i)
{
auto p = new int {7}; // bad: initialize local pointers with new
auto q = make_unique(9); // ok: guarantee the release of the memory-allocated for 9
if (0 < i) return; // maybe return and leak
delete p; // too late
}
##### Enforcement
* 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
See [R.23](#rr-make_unique)
### C.151: Use `make_shared()` to construct objects owned by `shared_ptr`s
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
##### Reason
Subscripting the resulting base pointer will lead to invalid object access and probably to memory corruption.
##### Example
struct B { int x; };
struct D : B { int y; };
void use(B*);
D a[] = { {1, 2}, {3, 4}, {5, 6} };
B* p = a; // bad: a decays to &a[0] which is converted to a B*
p[1].x = 7; // overwrite a[0].y
use(a); // bad: a decays to &a[0] which is converted to a B*
##### Enforcement
* Flag all combinations of array decay and base to derived conversions.
* 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
##### Reason
A virtual function call is safe, whereas casting is error-prone.
A virtual function call reaches the most derived function, whereas a cast might reach an intermediate class and therefore
give a wrong result (especially as a hierarchy is modified during maintenance).
##### Example
???
##### Enforcement
See [C.146](#rh-dynamic_cast) and ???
## 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
##### Reason
Minimize surprises.
##### Example
class X {
public:
// ...
X& operator=(const X&); // member function defining assignment
friend bool operator==(const X&, const X&); // == needs access to representation
// after a = b we have a == b
// ...
};
Here, the conventional semantics is maintained: [Copies compare equal](#ss-copy).
##### Example, bad
X operator+(X a, X b) { return a.v - b.v; } // bad: makes + subtract
##### 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).
##### Enforcement
Possibly impossible.
### C.161: Use non-member functions for symmetric operators
##### Reason
If you use member functions, you need two.
Unless you use a non-member function for (say) `==`, `a == b` and `b == a` will be subtly different.
##### Example
bool operator==(Point a, Point b) { return a.x == b.x && a.y == b.y; }
##### Enforcement
Flag member operator functions.
### C.162: Overload operations that are roughly equivalent
##### Reason
Having different names for logically equivalent operations on different argument types is confusing, leads to encoding type information in function names, and inhibits generic programming.
##### Example
Consider:
void print(int a);
void print(int a, int base);
void print(const string&);
These three functions all print their arguments (appropriately). Conversely:
void print_int(int a);
void print_based(int a, int base);
void print_string(const string&);
These three functions all print their arguments (appropriately). Adding to the name just introduced verbosity and inhibits generic code.
##### Enforcement
???
### C.163: Overload only for operations that are roughly equivalent
##### Reason
Having the same name for logically different functions is confusing and leads to errors when using generic programming.
##### Example
Consider:
void open_gate(Gate& g); // remove obstacle from garage exit lane
void fopen(const char* name, const char* mode); // open file
The two operations are fundamentally different (and unrelated) so it is good that their names differ. Conversely:
void open(Gate& g); // remove obstacle from garage exit lane
void open(const char* name, const char* mode ="r"); // open file
The two operations are still fundamentally different (and unrelated) but the names have been reduced to their (common) minimum, opening opportunities for confusion.
Fortunately, the type system will catch many such mistakes.
##### Note
Be particularly careful about common and popular names, such as `open`, `move`, `+`, and `==`.
##### Enforcement
???
### C.164: Avoid implicit conversion operators
##### Reason
Implicit conversions can be essential (e.g., `double` to `int`) but often cause surprises (e.g., `String` to C-style string).
##### Note
Prefer explicitly named conversions until a serious need is demonstrated.
By "serious need" we mean a reason that is fundamental in the application domain (such as an integer to complex number conversion)
and frequently needed. Do not introduce implicit conversions (through conversion operators or non-`explicit` constructors)
just to gain a minor convenience.
##### Example
struct S1 {
string s;
// ...
operator char*() { return s.data(); } // BAD, likely to cause surprises
};
struct S2 {
string s;
// ...
explicit operator char*() { return s.data(); }
};
void f(S1 s1, S2 s2)
{
char* x1 = s1; // OK, but can cause surprises in many contexts
char* x2 = s2; // error (and that's usually a good thing)
char* x3 = static_cast(s2); // we can be explicit (on your head be it)
}
The surprising and potentially damaging implicit conversion can occur in arbitrarily hard-to spot contexts, e.g.,
S1 ff();
char* g()
{
return ff();
}
The string returned by `ff()` is destroyed before the returned pointer into it can be used.
##### Enforcement
Flag all non-explicit conversion operators.
### C.165: Use `using` for customization points
##### Reason
To find function objects and functions defined in a separate namespace to "customize" a common function.
##### Example
Consider `swap`. It is a general (standard-library) function with a definition that will work for just about any type.
However, it is desirable to define specific `swap()`s for specific types.
For example, the general `swap()` will copy the elements of two `vector`s being swapped, whereas a good specific implementation will not copy elements at all.
namespace N {
My_type X { /* ... */ };
void swap(X&, X&); // optimized swap for N::X
// ...
}
void f1(N::X& a, N::X& b)
{
std::swap(a, b); // probably not what we wanted: calls std::swap()
}
The `std::swap()` in `f1()` does exactly what we asked it to do: it calls the `swap()` in namespace `std`.
Unfortunately, that's probably not what we wanted.
How do we get `N::X` considered?
void f2(N::X& a, N::X& b)
{
swap(a, b); // calls N::swap
}
But that might not be what we wanted for generic code.
There, we typically want the specific function if it exists and the general function if not.
This is done by including the general function in the lookup for the function:
void f3(N::X& a, N::X& b)
{
using std::swap; // make std::swap available
swap(a, b); // calls N::swap if it exists, otherwise std::swap
}
##### Enforcement
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
##### Reason
The `&` operator is fundamental in C++.
Many parts of the C++ semantics assume its default meaning.
##### Example
class Ptr { // a somewhat smart pointer
Ptr(X* pp) : p(pp) { /* check */ }
X* operator->() { /* check */ return p; }
X operator[](int i);
X operator*();
private:
T* p;
};
class X {
Ptr operator&() { return Ptr{this}; }
// ...
};
##### Note
If you "mess with" operator `&` be sure that its definition has matching meanings for `->`, `[]`, `*`, and `.` on the result type.
Note that operator `.` currently cannot be overloaded so a perfect system is impossible.
We hope to remedy that: [Operator Dot (R2)](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4477.pdf).
Note that `std::addressof()` always yields a built-in pointer.
##### Enforcement
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
##### Reason
Readability. Convention. Reusability. Support for generic code
##### Example
void cout_my_class(const My_class& c) // confusing, not conventional, not generic
{
std::cout << /* class members here */;
}
std::ostream& operator<<(std::ostream& os, const my_class& c) // OK
{
return os << /* class members here */;
}
By itself, `cout_my_class` would be OK, but it is not usable/composable with code that relies on the `<<` convention for output:
My_class var { /* ... */ };
// ...
cout << "var = " << var << '\n';
##### Note
There are strong and vigorous conventions for the meaning of most operators, such as
* comparisons (`==`, `!=`, `<`, `<=`, `>`, `>=`, and `<=>`),
* arithmetic operations (`+`, `-`, `*`, `/`, and `%`)
* access operations (`.`, `->`, unary `*`, and `[]`)
* assignment (`=`)
Don't define those unconventionally and don't invent your own names for them.
##### Enforcement
Tricky. Requires semantic insight.
### C.168: Define overloaded operators in the namespace of their operands
##### Reason
Readability.
Ability for find operators using ADL.
Avoiding inconsistent definition in different namespaces
##### Example
struct S { };
S operator+(S, S); // OK: in the same namespace as S, and even next to S
S s;
S r = s + s;
##### Example
namespace N {
struct S { };
S operator+(S, S); // OK: in the same namespace as S, and even next to S
}
N::S s;
S r = s + s; // finds N::operator+() by ADL
##### Example, bad
struct S { };
S s;
namespace N {
bool operator!(S a) { return true; }
bool not_s = !s;
}
namespace M {
bool operator!(S a) { return false; }
bool not_s = !s;
}
Here, the meaning of `!s` differs in `N` and `M`.
This can be most confusing.
Remove the definition of `namespace M` and the confusion is replaced by an opportunity to make the mistake.
##### Note
If a binary operator is defined for two types that are defined in different namespaces, you cannot follow this rule.
For example:
Vec::Vector operator*(const Vec::Vector&, const Mat::Matrix&);
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).
##### 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
##### Reason
You cannot overload by defining two different lambdas with the same name.
##### Example
void f(int);
void f(double);
auto f = [](char); // error: cannot overload variable and function
auto g = [](int) { /* ... */ };
auto g = [](double) { /* ... */ }; // error: cannot overload variables
auto h = [](auto) { /* ... */ }; // OK
##### Enforcement
The compiler catches the attempt to overload a lambda.
## 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;
this is inherently error-prone, but there are ways to compensate.
A type that is a `union` plus an indicator of which member is currently held is called a *tagged union*, a *discriminated union*, or a *variant*.
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
##### Reason
A `union` allows a single piece of memory to be used for different types of objects at different times.
Consequently, it can be used to save memory when we have several objects that are never used at the same time.
##### Example
union Value {
int x;
double d;
};
Value v = { 123 }; // now v holds an int
cout << v.x << '\n'; // write 123
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)
##### Example
// Short-string optimization
constexpr size_t buffer_size = 16; // Slightly larger than the size of a pointer
class Immutable_string {
public:
Immutable_string(const char* str) :
size(strlen(str))
{
if (size < buffer_size)
strcpy_s(string_buffer, buffer_size, str);
else {
string_ptr = new char[size + 1];
strcpy_s(string_ptr, size + 1, str);
}
}
~Immutable_string()
{
if (size >= buffer_size)
delete[] string_ptr;
}
const char* get_str() const
{
return (size < buffer_size) ? string_buffer : string_ptr;
}
private:
// If the string is short enough, we store the string itself
// instead of a pointer to the string.
union {
char* string_ptr;
char string_buffer[buffer_size];
};
const size_t size;
};
##### Enforcement
???
### C.181: Avoid "naked" `union`s
##### Reason
A *naked union* is a union without an associated indicator which member (if any) it holds,
so that the programmer has to keep track.
Naked unions are a source of type errors.
##### Example, bad
union Value {
int x;
double d;
};
Value v;
v.d = 987.654; // v holds a double
So far, so good, but we can easily misuse the `union`:
cout << v.x << '\n'; // BAD, undefined behavior: v holds a double, but we read it as an int
Note that the type error happened without any explicit cast.
When we tested that program the last value printed was `1683627180` which is the integer value for the bit pattern for `987.654`.
What we have here is an "invisible" type error that happens to give a result that could easily look innocent.
And, talking about "invisible", this code produced no output:
v.x = 123;
cout << v.d << '\n'; // BAD: undefined behavior
##### Alternative
Wrap a `union` in a class together with a type field.
The C++17 `variant` type (found in ``) does that for you:
variant v;
v = 123; // v holds an int
int x = get(v);
v = 123.456; // v holds a double
double w = get(v);
##### Enforcement
???
### C.182: Use anonymous `union`s to implement tagged unions
##### Reason
A well-designed tagged union is type safe.
An *anonymous* union simplifies the definition of a class with a (tag, union) pair.
##### Example
This example is mostly borrowed from TC++PL4, pp. 216--218.
You can look there for an explanation.
The code is somewhat elaborate.
Handling a type with user-defined assignment and destructor is tricky.
Saving programmers from having to write such code is one reason for including `variant` in the standard.
class Value { // two alternative representations represented as a union
private:
enum class Tag { number, text };
Tag type; // discriminant
union { // representation (note: anonymous union)
int i;
string s; // string has default constructor, copy operations, and destructor
};
public:
struct Bad_entry { }; // used for exceptions
~Value();
Value& operator=(const Value&); // necessary because of the string variant
Value(const Value&);
// ...
int number() const;
string text() const;
void set_number(int n);
void set_text(const string&);
// ...
};
int Value::number() const
{
if (type != Tag::number) throw Bad_entry{};
return i;
}
string Value::text() const
{
if (type != Tag::text) throw Bad_entry{};
return s;
}
void Value::set_number(int n)
{
if (type == Tag::text) {
s.~string(); // explicitly destroy string
type = Tag::number;
}
i = n;
}
void Value::set_text(const string& ss)
{
if (type == Tag::text)
s = ss;
else {
new(&s) string{ss}; // placement new: explicitly construct string
type = Tag::text;
}
}
Value& Value::operator=(const Value& e) // necessary because of the string variant
{
if (type == Tag::text && e.type == Tag::text) {
s = e.s; // usual string assignment
return *this;
}
if (type == Tag::text) s.~string(); // explicit destroy
switch (e.type) {
case Tag::number:
i = e.i;
break;
case Tag::text:
new(&s) string(e.s); // placement new: explicit construct
}
type = e.type;
return *this;
}
Value::~Value()
{
if (type == Tag::text) s.~string(); // explicit destroy
}
##### Enforcement
???
### C.183: Don't use a `union` for type punning
##### Reason
It is undefined behavior to read a `union` member with a different type from the one with which it was written.
Such punning is invisible, or at least harder to spot than using a named cast.
Type punning using a `union` is a source of errors.
##### Example, bad
union Pun {
int x;
unsigned char c[sizeof(int)];
};
The idea of `Pun` is to be able to look at the character representation of an `int`.
void bad(Pun& u)
{
u.x = 'x';
cout << u.c[0] << '\n'; // undefined behavior
}
If you wanted to see the bytes of an `int`, use a (named) cast:
void if_you_must_pun(int& x)
{
auto p = reinterpret_cast(&x);
cout << to_integer(p[0]) << '\n'; // OK; better
// ...
}
Accessing the result of a `reinterpret_cast` from the object's declared type to `char*`, `unsigned char*`, or `std::byte*` is defined behavior. (Using `reinterpret_cast` is discouraged,
but at least we can see that something tricky is going on.)
##### Note
Unfortunately, `union`s are commonly used for type punning.
We don't consider "sometimes, it works as expected" a conclusive argument.
Modern C++ introduced `std::byte` (C++17) and `std::bit_cast` (C++20) to facilitate operations on raw object representations.
Use `reinterpret_cast` along with `std::byte` instead of `unsigned char` or `char` for these operations.
##### Enforcement
???
# 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
##### Reason
Macros do not obey scope and type rules. Also, macro names are removed during preprocessing and so usually don't appear in tools like debuggers.
##### Example
First some bad old code:
// webcolors.h (third party header)
#define RED 0xFF0000
#define GREEN 0x00FF00
#define BLUE 0x0000FF
// productinfo.h
// The following define product subtypes based on color
#define RED 0
#define PURPLE 1
#define BLUE 2
int webby = BLUE; // webby == 2; probably not what was desired
Instead use an `enum`:
enum class Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
enum class Product_info { red = 0, purple = 1, blue = 2 };
int webby = blue; // error: be specific
Web_color webby = Web_color::blue;
We used an `enum class` to avoid name clashes.
##### Note
Also consider `constexpr` and `const inline` variables.
##### Enforcement
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
##### Reason
An enumeration shows the enumerators to be related and can be a named type.
##### Example
enum class Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
##### Note
Switching on an enumeration is common and the compiler can warn against unusual patterns of case labels. For example:
enum class Product_info { red = 0, purple = 1, blue = 2 };
void print(Product_info inf)
{
switch (inf) {
case Product_info::red: cout << "red"; break;
case Product_info::purple: cout << "purple"; break;
}
}
Such off-by-one `switch`-statements are often the results of an added enumerator and insufficient testing.
##### Enforcement
* Flag `switch`-statements where the `case`s cover most but not all enumerators of an enumeration.
* 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
##### Reason
To minimize surprises: traditional enums convert to int too readily.
##### Example
void Print_color(int color);
enum Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
enum Product_info { red = 0, purple = 1, blue = 2 };
Web_color webby = Web_color::blue;
// Clearly at least one of these calls is buggy.
Print_color(webby);
Print_color(Product_info::blue);
Instead use an `enum class`:
void Print_color(int color);
enum class Web_color { red = 0xFF0000, green = 0x00FF00, blue = 0x0000FF };
enum class Product_info { red = 0, purple = 1, blue = 2 };
Web_color webby = Web_color::blue;
Print_color(webby); // Error: cannot convert Web_color to int.
Print_color(Product_info::red); // Error: cannot convert Product_info to int.
##### Enforcement
(Simple) Warn on any non-class `enum` definition.
### Enum.4: Define operations on enumerations for safe and simple use
##### Reason
Convenience of use and avoidance of errors.
##### Example
enum class Day { mon, tue, wed, thu, fri, sat, sun };
Day& operator++(Day& d)
{
return d = (d == Day::sun) ? Day::mon : static_cast(static_cast(d)+1);
}
Day today = Day::sat;
Day tomorrow = ++today;
The use of a `static_cast` is not pretty, but
Day& operator++(Day& d)
{
return d = (d == Day::sun) ? Day::mon : Day{++d}; // error
}
is an infinite recursion, and writing it without a cast, using a `switch` on all cases is long-winded.
##### Enforcement
Flag repeated expressions cast back into an enumeration.
### Enum.5: Don't use `ALL_CAPS` for enumerators
##### Reason
Avoid clashes with macros.
##### Example, bad
// webcolors.h (third party header)
#define RED 0xFF0000
#define GREEN 0x00FF00
#define BLUE 0x0000FF
// productinfo.h
// The following define product subtypes based on color
enum class Product_info { RED, PURPLE, BLUE }; // syntax error
##### Enforcement
Flag ALL_CAPS enumerators.
### Enum.6: Avoid unnamed enumerations
##### Reason
If you can't name an enumeration, the values are not related
##### Example, bad
enum { red = 0xFF0000, scale = 4, is_signed = 1 };
Such code is not uncommon in code written before there were convenient alternative ways of specifying integer constants.
##### Alternative
Use `constexpr` values instead. For example:
constexpr int red = 0xFF0000;
constexpr short scale = 4;
constexpr bool is_signed = true;
##### Enforcement
Flag unnamed enumerations.
### Enum.7: Specify the underlying type of an enumeration only when necessary
##### Reason
The default is the easiest to read and write.
`int` is the default integer type.
`int` is compatible with C `enum`s.
##### Example
enum class Direction : char { n, s, e, w,
ne, nw, se, sw }; // underlying type saves space
enum class Web_color : int32_t { red = 0xFF0000,
green = 0x00FF00,
blue = 0x0000FF }; // underlying type is redundant
##### Note
Specifying the underlying type is necessary to forward-declare an enum or enum class:
enum Flags : char;
void f(Flags);
// ....
enum Flags : char { /* ... */ };
or to ensure that values of that type have a specified bit-precision:
enum Bitboard : uint64_t { /* ... */ };
##### Enforcement
????
### Enum.8: Specify enumerator values only when necessary
##### Reason
It's the simplest.
It avoids duplicate enumerator values.
The default gives a consecutive set of values that is good for `switch`-statement implementations.
##### Example
enum class Col1 { red, yellow, blue };
enum class Col2 { red = 1, yellow = 2, blue = 2 }; // typo
enum class Month { jan = 1, feb, mar, apr, may, jun,
jul, august, sep, oct, nov, dec }; // starting with 1 is conventional
enum class Base_flag { dec = 1, oct = dec << 1, hex = dec << 2 }; // set of bits
Specifying values is necessary to match conventional values (e.g., `Month`)
and where consecutive values are undesirable (e.g., to get separate bits as in `Base_flag`).
##### Enforcement
* Flag duplicate enumerator values
* Flag explicitly specified all-consecutive enumerator values
# 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.
The reason it must be released is typically that it can be in short supply, so even delayed release might do harm.
The fundamental aim is to ensure that we don't leak any resources and that we don't hold a resource longer than we need to.
An entity that is responsible for releasing a resource is called an owner.
There are a few cases where leaks can be acceptable or even optimal:
If you are writing a program that simply produces an output based on an input and the amount of memory needed is proportional to the size of the input, the optimal strategy (for performance and ease of programming) is sometimes simply never to delete anything.
If you have enough memory to handle your largest input, leak away, but be sure to give a good error message if you are wrong.
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)
* 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)
* 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