Merge pull request #327 from pwnall/update_cpp
Update C++ styleguide to revision 3.277
diff --git a/cppguide.html b/cppguide.html
index 590cc9f..7f837ac 100644
--- a/cppguide.html
+++ b/cppguide.html
@@ -1,11 +1,11 @@
<!DOCTYPE html>
-<html>
+<html lang="en">
<head>
-<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+<meta charset="utf-8">
<title>Google C++ Style Guide</title>
-<link rel="stylesheet" type="text/css" href="include/styleguide.css">
-<script language="javascript" src="include/styleguide.js"></script>
-<link rel="shortcut icon" type="image/x-icon" href="https://www.google.com/favicon.ico" />
+<link rel="stylesheet" href="include/styleguide.css">
+<script src="include/styleguide.js"></script>
+<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
</head>
<body onload="initStyleGuide();">
<div id="content">
@@ -427,10 +427,14 @@
<ol>
<li><code><var>dir2/foo2</var>.h</code>.</li>
+ <li>A blank line</li>
+
<li>C system files.</li>
<li>C++ system files.</li>
+ <li>A blank line</li>
+
<li>Other libraries' <code>.h</code>
files.</li>
@@ -439,6 +443,8 @@
files.</li>
</ol>
+<p>Note that any adjacent blank lines should be collapsed.</p>
+
<p>With the preferred ordering, if
<code><var>dir2/foo2</var>.h</code> omits any necessary
includes, the build of <code><var>dir/foo</var>.cc</code>
@@ -455,6 +461,11 @@
+<p>Note that the C compatibility headers such as <code>stddef.h</code>
+are essentially interchangeable with their C++ counterparts
+(<code>cstddef</code>)
+Either style is acceptable, but prefer consistency with existing code.</p>
+
<p>Within each section the includes should be ordered
alphabetically. Note that older code might not conform to
this rule and should be fixed when convenient.</p>
@@ -480,8 +491,6 @@
#include <sys/types.h>
#include <unistd.h>
-
-#include <hash_map>
#include <vector>
#include "base/basictypes.h"
@@ -545,15 +554,15 @@
the enclosing scope. Consider the following snippet, for
example:</p>
-<pre>namespace X {
-inline namespace Y {
+<pre>namespace outer {
+inline namespace inner {
void foo();
-} // namespace Y
-} // namespace X
+} // namespace inner
+} // namespace outer
</pre>
-<p>The expressions <code>X::Y::foo()</code> and
-<code>X::foo()</code> are interchangeable. Inline
+<p>The expressions <code>outer::inner::foo()</code> and
+<code>outer::foo()</code> are interchangeable. Inline
namespaces are primarily intended for ABI compatibility
across versions.</p>
</div>
@@ -621,13 +630,13 @@
DEFINE_FLAG(bool, someflag, false, "dummy flag");
-namespace a {
+namespace mynamespace {
using ::foo::bar;
-...code for a... // Code goes against the left margin.
+...code for mynamespace... // Code goes against the left margin.
-} // namespace a
+} // namespace mynamespace
</pre>
</li>
@@ -690,11 +699,11 @@
<div class="stylebody">
<div class="definition">
-<p>All declarations can be given internal linkage by placing them in
-unnamed namespaces, and functions and variables can be given internal linkage by
+<p>All declarations can be given internal linkage by placing them in unnamed
+namespaces. Functions and variables can also be given internal linkage by
declaring them <code>static</code>. This means that anything you're declaring
-can't be accessed from another file. If a different file declares something
-with the same name, then the two entities are completely independent.</p>
+can't be accessed from another file. If a different file declares something with
+the same name, then the two entities are completely independent.</p>
</div>
<div class="decision">
@@ -717,10 +726,9 @@
<div class="summary">
<p>Prefer placing nonmember functions in a namespace; use completely global
-functions rarely. Prefer grouping functions with a namespace instead of
-using a class as if it were a namespace. Static methods of a class should
-generally be closely related to instances of the class or the class's static
-data.</p>
+functions rarely. Do not use a class simply to group static functions. Static
+methods of a class should generally be closely related to instances of the
+class or the class's static data.</p>
</div>
<div class="stylebody">
@@ -743,26 +751,9 @@
can be either a static member or a nonmember function.
Nonmember functions should not depend on external
variables, and should nearly always exist in a namespace.
-Rather than creating classes only to group static member
-functions which do not share static data, use
-<a href="#Namespaces">namespaces</a> instead. For a header
-<code>myproject/foo_bar.h</code>, for example, write</p>
-<pre>namespace myproject {
-namespace foo_bar {
-void Function1();
-void Function2();
-} // namespace foo_bar
-} // namespace myproject
-</pre>
-<p>instead of</p>
-<pre class="badcode">namespace myproject {
-class FooBar {
- public:
- static void Function1();
- static void Function2();
-};
-} // namespace myproject
-</pre>
+Do not create classes only to group static member functions;
+this is no different than just giving the function names a
+common prefix, and such grouping is usually unnecessary anyway.</p>
<p>If you define a nonmember function and it is only
needed in its <code>.cc</code> file, use
@@ -838,85 +829,281 @@
<h3 id="Static_and_Global_Variables">Static and Global Variables</h3>
<div class="summary">
- <p>Variables of class type with <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration">
- static storage duration</a> are forbidden: they cause hard-to-find bugs due
- to indeterminate order of construction and destruction. However, such
- variables are allowed if they are <code>constexpr</code>: they have no
- dynamic initialization or destruction.</p>
+<p>Objects with
+<a href="http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration">
+static storage duration</a> are forbidden unless they are
+<a href="http://en.cppreference.com/w/cpp/types/is_destructible">trivially
+destructible</a>. Informally this means that the destructor does not do
+anything, even taking member and base destructors into account. More formally it
+means that the type has no user-defined or virtual destructor and that all bases
+and non-static members are trivially destructible.
+Static function-local variables may use dynamic initialization.
+Use of dynamic initialization for static class member variables or variables at
+namespace scope is discouraged, but allowed in limited circumstances; see below
+for details.</p>
+
+<p>As a rule of thumb: a global variable satisfies these requirements if its
+declaration, considered in isolation, could be <code>constexpr</code>.</p>
</div>
<div class="stylebody">
-<p>Objects with static storage duration, including global
-variables, static variables, static class member
-variables, and function static variables, must be Plain
-Old Data (POD): only ints, chars, floats, or pointers, or
-arrays/structs of POD.</p>
+<div class="definition">
+<p>Every object has a <dfn>storage duration</dfn>, which correlates with its
+lifetime. Objects with static storage duration live from the point of their
+initialization until the end of the program. Such objects appear as variables at
+namespace scope ("global variables"), as static data members of classes, or as
+function-local variables that are declared with the <code>static</code>
+specifier. Function-local static variables are initialized when control first
+passes through their declaration; all other objects with static storage duration
+are initialized as part of program start-up. All objects with static storage
+duration are destroyed at program exit (which happens before unjoined threads
+are terminated).</p>
-<p>The order in which class constructors and initializers
-for static variables are called is only partially
-specified in C++ and can even change from build to build,
-which can cause bugs that are difficult to find.
-Therefore in addition to banning globals of class type,
-we do not allow non-local static variables to be initialized
-with the result of a function, unless that function (such
-as getenv(), or getpid()) does not itself depend on any
-other globals. However, a static POD variable within
-function scope may be initialized with the result of a
-function, since its initialization order is well-defined
-and does not occur until control passes through its
-declaration.</p>
+<p>Initialization may be <dfn>dynamic</dfn>, which means that something
+non-trivial happens during initialization. (For example, consider a constructor
+that allocates memory, or a variable that is initialized with the current
+process ID.) The other kind of initialization is <dfn>static</dfn>
+initialization. The two aren't quite opposites, though: static
+initialization <em>always</em> happens to objects with static storage duration
+(initializing the object either to a given constant or to a representation
+consisting of all bytes set to zero), whereas dynamic initialization happens
+after that, if required.</p>
+</div>
-<p>Likewise, global and static variables are destroyed
-when the program terminates, regardless of whether the
-termination is by returning from <code>main()</code> or
-by calling <code>exit()</code>. The order in which
-destructors are called is defined to be the reverse of
-the order in which the constructors were called. Since
-constructor order is indeterminate, so is destructor
-order. For example, at program-end time a static variable
-might have been destroyed, but code still running
-— perhaps in another thread
-— tries to access it and fails. Or the
-destructor for a static <code>string</code> variable
-might be run prior to the destructor for another variable
-that contains a reference to that string.</p>
+<div class="pros">
+<p>Global and static variables are very useful for a large number of
+applications: named constants, auxiliary data structures internal to some
+translation unit, command-line flags, logging, registration mechanisms,
+background infrastructure, etc.</p>
+</div>
-<p>One way to alleviate the destructor problem is to
-terminate the program by calling
-<code>quick_exit()</code> instead of <code>exit()</code>.
-The difference is that <code>quick_exit()</code> does not
-invoke destructors and does not invoke any handlers that
-were registered by calling <code>atexit()</code>. If you
-have a handler that needs to run when a program
-terminates via <code>quick_exit()</code> (flushing logs,
-for example), you can register it using
-<code>at_quick_exit()</code>. (If you have a handler that
-needs to run at both <code>exit()</code> and
-<code>quick_exit()</code>, you need to register it in
-both places.)</p>
+<div class="cons">
+<p>Global and static variables that use dynamic initialization or have
+non-trivial destructors create complexity that can easily lead to hard-to-find
+bugs. Dynamic initialization is not ordered across translation units, and
+neither is destruction (except that destruction
+happens in reverse order of initialization). When one initialization refers to
+another variable with static storage duration, it is possible that this causes
+an object to be accessed before its lifetime has begun (or after its lifetime
+has ended). Moreover, when a program starts threads that are not joined at exit,
+those threads may attempt to access objects after their lifetime has ended if
+their destructor has already run.</p>
+</div>
-<p>As a result we only allow static variables to contain
-POD data. This rule completely disallows
-<code>std::vector</code> (use C arrays instead), or
-<code>string</code> (use <code>const char []</code>).</p>
+<div class="decision">
+<h4>Decision on destruction</h4>
+
+<p>When destructors are trivial, their execution is not subject to ordering at
+all (they are effectively not "run"); otherwise we are exposed to the risk of
+accessing objects after the end of their lifetime. Therefore, we only allow
+objects with static storage duration if they are trivially destructible.
+Fundamental types (like pointers and <code>int</code>) are trivially
+destructible, as are arrays of trivially destructible types. Note that
+variables marked with <code>constexpr</code> are trivially destructible.</p>
+<pre>const int kNum = 10; // allowed
+
+struct X { int n; };
+const X kX[] = {{1}, {2}, {3}}; // allowed
+
+void foo() {
+ static const char* const kMessages[] = {"hello", "world"}; // allowed
+}
+
+// allowed: constexpr guarantees trivial destructor
+constexpr std::array<int, 3> kArray = {{1, 2, 3}};</pre>
+<pre class="badcode">// bad: non-trivial destructor
+const string kFoo = "foo";
+
+// bad for the same reason, even though kBar is a reference (the
+// rule also applies to lifetime-extended temporary objects)
+const string& kBar = StrCat("a", "b", "c");
+
+void bar() {
+ // bad: non-trivial destructor
+ static std::map<int, int> kData = {{1, 0}, {2, 0}, {3, 0}};
+}</pre>
+
+<p>Note that references are not objects, and thus they are not subject to the
+constraints on destructibility. The constraint on dynamic initialization still
+applies, though. In particular, a function-local static reference of the form
+<code>static T& t = *new T;</code> is allowed.</p>
+
+<h4>Decision on initialization</h4>
+
+<p>Initialization is a more complex topic. This is because we must not only
+consider whether class constructors execute, but we must also consider the
+evaluation of the initializer:</p>
+<pre class="neutralcode">int n = 5; // fine
+int m = f(); // ? (depends on f)
+Foo x; // ? (depends on Foo::Foo)
+Bar y = g(); // ? (depends on g and on Bar::Bar)</pre>
+
+<p>All but the first statement expose us to indeterminate initialization
+ordering.</p>
+
+<p>The concept we are looking for is called <em>constant initialization</em> in
+the formal language of the C++ standard. It means that the initializing
+expression is a constant expression, and if the object is initialized by a
+constructor call, then the constructor must be specified as
+<code>constexpr</code>, too:</p>
+<pre>struct Foo { constexpr Foo(int) {} };
+
+int n = 5; // fine, 5 is a constant expression
+Foo x(2); // fine, 2 is a constant expression and the chosen constructor is constexpr
+Foo a[] = { Foo(1), Foo(2), Foo(3) }; // fine</pre>
+
+<p>Constant initialization is always allowed. Constant initialization of
+static storage duration variables should be marked with <code>constexpr</code>
+where possible. Any non-local static storage
+duration variable that is not so marked should be presumed to have
+dynamic initialization, and reviewed very carefully.</p>
+
+<p>By contrast, the following initializations are problematic:</p>
+
+<pre class="neutralcode">time_t time(time_t*); // not constexpr!
+int f(); // not constexpr!
+struct Bar { Bar() {} };
+
+time_t m = time(nullptr); // initializing expression not a constant expression
+Foo y(f()); // ditto
+Bar b; // chosen constructor Bar::Bar() not constexpr</pre>
+
+<p>Dynamic initialization of nonlocal variables is discouraged, and in general
+it is forbidden. However, we do permit it if no aspect of the program depends
+on the sequencing of this initialization with respect to all other
+initializations. Under those restrictions, the ordering of the initialization
+does not make an observable difference. For example:</p>
+<pre>int p = getpid(); // allowed, as long as no other static variable
+ // uses p in its own initialization</pre>
+
+<p>Dynamic initialization of static local variables is allowed (and common).</p>
+</div>
-<p>If you need a static or global
-variable of a class type, consider initializing a pointer
-(which will never be freed), from either your main()
-function or from pthread_once(). Note that this must be a
-raw pointer, not a "smart" pointer, since the smart
-pointer's destructor will have the order-of-destructor
-issue that we are trying to avoid.</p>
+<h4>Common patterns</h4>
-
-
-
+<ul>
+ <li>Global strings: if you require a global or static string constant,
+ consider using a simple character array, or a char pointer to the first
+ element of a string literal. String literals have static storage duration
+ already and are usually sufficient.</li>
+ <li>Maps, sets, and other dynamic containers: if you require a static, fixed
+ collection, such as a set to search against or a lookup table, you cannot
+ use the dynamic containers from the standard library as a static variable,
+ since they have non-trivial destructors. Instead, consider a simple array of
+ trivial types, e.g. an array of arrays of ints (for a "map from int to
+ int"), or an array of pairs (e.g. pairs of <code>int</code> and <code>const
+ char*</code>). For small collections, linear search is entirely sufficient
+ (and efficient, due to memory locality). If necessary, keep the collection in
+ sorted order and use a binary search algorithm. If you do really prefer a
+ dynamic container from the standard library, consider using a function-local
+ static pointer, as described below.</li>
+ <li>Smart pointers (<code>unique_ptr</code>, <code>shared_ptr</code>): smart
+ pointers execute cleanup during destruction and are therefore forbidden.
+ Consider whether your use case fits into one of the other patterns described
+ in this section. One simple solution is to use a plain pointer to a
+ dynamically allocated object and never delete it (see last item).</li>
+ <li>Static variables of custom types: if you require static, constant data of
+ a type that you need to define yourself, give the type a trivial destructor
+ and a <code>constexpr</code> constructor.</li>
+ <li>If all else fails, you can create an object dynamically and never delete
+ it by binding the pointer to a function-local static pointer variable:
+ <code>static const auto* const impl = new T(args...);</code> (If the
+ initialization is more complex, it can be moved into a function or lambda
+ expression.)</li>
+</ul>
</div>
+<h3 id="thread_local">thread_local Variables</h3>
+
+<div class="summary">
+<p><code>thread_local</code> variables that aren't declared inside a function
+must be initialized with a true compile-time constant. Prefer
+<code>thread_local</code> over other ways of defining thread-local data.</p>
+</div>
+
+<div class="stylebody">
+
+<div class="definition">
+<p>Starting with C++11, variables can be declared with the
+<code>thread_local</code> specifier:</p>
+<pre>thread_local Foo foo = ...;
+</pre>
+<p>Such a variable is actually a collection of objects, so that when different
+threads access it, they are actually accessing different objects.
+<code>thread_local</code> variables are much like
+<a href="#Static_and_Global_Variables">static storage duration variables</a>
+in many respects. For instance, they can be declared at namespace scope,
+inside functions, or as static class members, but not as ordinary class
+members.</p>
+
+<p><code>thread_local</code> variable instances are initialized much like
+static variables, except that they must be initialized separately for each
+thread, rather than once at program startup. This means that
+<code>thread_local</code> variables declared within a function are safe, but
+other <code>thread_local</code> variables are subject to the same
+initialization-order issues as static variables (and more besides).</p>
+
+<p><code>thread_local</code> variable instances are destroyed when their thread
+terminates, so they do not have the destruction-order issues of static
+variables.</p>
+</div>
+
+<div class="pros">
+<ul>
+ <li>Thread-local data is inherently safe from races (because only one thread
+ can ordinarily access it), which makes <code>thread_local</code> useful for
+ concurrent programming.</li>
+ <li><code>thread_local</code> is the only standard-supported way of creating
+ thread-local data.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+ <li>Accessing a <code>thread_local</code> variable may trigger execution of
+ an unpredictable and uncontrollable amount of other code.</li>
+ <li><code>thread_local</code> variables are effectively global variables,
+ and have all the drawbacks of global variables other than lack of
+ thread-safety.</li>
+ <li>The memory consumed by a <code>thread_local</code> variable scales with
+ the number of running threads (in the worst case), which can be quite large
+ in a program.</li>
+ <li>An ordinary class member cannot be <code>thread_local</code>.</li>
+ <li><code>thread_local</code> may not be as efficient as certain compiler
+ intrinsics.</li>
+</ul>
+</div>
+
+<div class="decision">
+ <p><code>thread_local</code> variables inside a function have no safety
+ concerns, so they can be used without restriction. Note that you can use
+ a function-scope <code>thread_local</code> to simulate a class- or
+ namespace-scope <code>thread_local</code> by defining a function or
+ static method that exposes it:</p>
+
+<pre>Foo& MyThreadLocalFoo() {
+ thread_local Foo result = ComplicatedInitialization();
+ return result;
+}
+</pre>
+
+ <p><code>thread_local</code> variables at class or namespace scope must be
+ initialized with a true compile-time constant (i.e. they must have no
+ dynamic initialization). </p>
+
+
+
+ <p><code>thread_local</code> should be preferred over other mechanisms for
+ defining thread-local data.</p>
+</div>
+
+</div>
+
+
<h2 id="Classes">Classes</h2>
<p>Classes are the fundamental unit of code in C++. Naturally,
@@ -1086,7 +1273,7 @@
a waiver of this rule.</p>
<p>Constructors that cannot be called with a single argument
-should usually omit <code>explicit</code>. Constructors that
+may omit <code>explicit</code>. Constructors that
take a single <code>std::initializer_list</code> parameter should
also omit <code>explicit</code>, in order to support copy-initialization
(e.g. <code>MyType m = {1, 2};</code>).</p>
@@ -1097,25 +1284,32 @@
<h3 id="Copyable_Movable_Types">Copyable and Movable Types</h3>
<a id="Copy_Constructors"></a>
<div class="summary">
-<p>Support copying and/or moving if these operations are clear and meaningful
-for your type. Otherwise, disable the implicitly generated special functions
-that perform copies and moves.
-</p></div>
+<p>A class's public API should make explicit whether the class is copyable,
+move-only, or neither copyable nor movable. Support copying and/or
+moving if these operations are clear and meaningful for your type.</p>
+</div>
<div class="stylebody">
<div class="definition">
-<p>A copyable type allows its objects to be initialized or assigned
-from any other object of the same type, without changing the value of the source.
-For user-defined types, the copy behavior is defined by the copy
-constructor and the copy-assignment operator.
-<code>string</code> is an example of a copyable type.</p>
-
<p>A movable type is one that can be initialized and assigned
-from temporaries (all copyable types are therefore movable).
+from temporaries.</p>
+
+<p>A copyable type is one that can be initialized or assigned from
+any other object of the same type (so is also movable by definition), with the
+stipulation that the value of the source does not change.
<code>std::unique_ptr<int></code> is an example of a movable but not
-copyable type. For user-defined types, the move behavior is defined by the move
-constructor and the move-assignment operator.</p>
+copyable type (since the value of the source
+<code>std::unique_ptr<int></code> must be modified during assignment to
+the destination). <code>int</code> and <code>string</code> are examples of
+movable types that are also copyable. (For <code>int</code>, the move and copy
+operations are the same; for <code>string</code>, there exists a move operation
+that is less expensive than a copy.)</p>
+
+<p>For user-defined types, the copy behavior is defined by the copy
+constructor and the copy-assignment operator. Move behavior is defined by the
+move constructor and the move-assignment operator, if they exist, or by the
+copy constructor and the copy-assignment operator otherwise.</p>
<p>The copy/move constructors can be implicitly invoked by the compiler
in some situations, e.g. when passing objects by value.</p>
@@ -1170,49 +1364,82 @@
<div class="decision">
-<p>Provide the copy and move operations if their meaning is clear to a casual
-user and the copying/moving does not incur unexpected costs. If you define a
-copy or move constructor, define the corresponding assignment operator, and
-vice-versa. If your type is copyable, do not define move operations unless they
-are significantly more efficient than the corresponding copy operations. If your
-type is not copyable, but the correctness of a move is obvious to users of the
-type, you may make the type move-only by defining both of the move operations.
-</p>
+<p>Every class's public interface should make explicit which copy and move
+operations the class supports. This should usually take the form of explicitly
+declaring and/or deleting the appropriate operations in the <code>public</code>
+section of the declaration.</p>
-<p>If your type provides copy operations, it is recommended that you design
-your class so that the default implementation of those operations is correct.
-Remember to review the correctness of any defaulted operations as you would any
-other code, and to document that your class is copyable and/or cheaply movable
-if that's an API guarantee.</p>
+<p>Specifically, a copyable class should explicitly declare the copy
+operations, a move-only class should explicitly declare the move operations,
+and a non-copyable/movable class should explicitly delete the copy operations.
+Explicitly declaring or deleting all four copy/move operations is permitted,
+but not required. If you provide a copy or move assignment operator, you
+must also provide the corresponding constructor.</p>
-<pre class="badcode">class Foo {
+<pre>class Copyable {
public:
- Foo(Foo&& other) : field_(other.field) {}
- // Bad, defines only move constructor, but not operator=.
+ Copyable(const Copyable& rhs) = default;
+ Copyable& operator=(const Copyable& rhs) = default;
- private:
- Field field_;
+ // The implicit move operations are suppressed by the declarations above.
+};
+
+class MoveOnly {
+ public:
+ MoveOnly(MoveOnly&& rhs);
+ MoveOnly& operator=(MoveOnly&& rhs);
+
+ // The copy operations are implicitly deleted, but you can
+ // spell that out explicitly if you want:
+ MoveOnly(const MoveOnly&) = delete;
+ MoveOnly& operator=(const MoveOnly&) = delete;
+};
+
+class NotCopyableOrMovable {
+ public:
+ // Not copyable or movable
+ NotCopyableOrMovable(const NotCopyableOrMovable&) = delete;
+ NotCopyableOrMovable& operator=(const NotCopyableOrMovable&)
+ = delete;
+
+ // The move operations are implicitly disabled, but you can
+ // spell that out explicitly if you want:
+ NotCopyableOrMovable(NotCopyableOrMovable&&) = delete;
+ NotCopyableOrMovable& operator=(NotCopyableOrMovable&&)
+ = delete;
};
</pre>
-<p>Due to the risk of slicing, avoid providing an assignment
-operator or public copy/move constructor for a class that's
-intended to be derived from (and avoid deriving from a class
+<p>These declarations/deletions can be omitted only if they are obvious: for
+example, if a base class isn't copyable or movable, derived classes naturally
+won't be either. Similarly, a <a href="#Structs_vs._Classes">struct</a>'s
+copyability/movability is normally determined by the copyability/movability
+of its data members (this does not apply to classes because in Google code
+their data members are not public). Note that if you explicitly declare or
+delete any of the copy/move operations, the others are not obvious, and so
+this paragraph does not apply (in particular, the rules in this section
+that apply to "classes" also apply to structs that declare or delete any
+copy/move operations).</p>
+
+<p>A type should not be copyable/movable if the meaning of
+copying/moving is unclear to a casual user, or if it incurs unexpected
+costs. Move operations for copyable types are strictly a performance
+optimization and are a potential source of bugs and complexity, so
+avoid defining them unless they are significantly more efficient than
+the corresponding copy operations. If your type provides copy operations, it is
+recommended that you design your class so that the default implementation of
+those operations is correct. Remember to review the correctness of any
+defaulted operations as you would any other code.</p>
+
+<p>Due to the risk of slicing, prefer to avoid providing a public assignment
+operator or copy/move constructor for a class that's
+intended to be derived from (and prefer to avoid deriving from a class
with such members). If your base class needs to be
copyable, provide a public virtual <code>Clone()</code>
method, and a protected copy constructor that derived classes
can use to implement it.</p>
-<p>If you do not want to support copy/move operations on your type,
-explicitly disable them using <code>= delete</code> in
-the <code>public:</code> section:</p>
-<pre class="code">// MyClass is neither copyable nor movable.
-MyClass(const MyClass&) = delete;
-MyClass& operator=(const MyClass&) = delete;
-</pre>
-
-<p></p>
</div>
</div>
@@ -1294,9 +1521,7 @@
the sub-class, it can be more difficult to understand an
implementation. The sub-class cannot override functions
that are not virtual, so the sub-class cannot change
-implementation. The base class may also define some data
-members, so that specifies physical layout of the base
-class.</p>
+implementation.</p>
</div>
<div class="decision">
@@ -1312,23 +1537,15 @@
that <code>Bar</code> "is a kind of"
<code>Foo</code>.</p>
-<p>Make your destructor <code>virtual</code> if
-necessary. If your class has virtual methods, its
-destructor should be virtual.</p>
-
<p>Limit the use of <code>protected</code> to those
member functions that might need to be accessed from
subclasses. Note that <a href="#Access_Control">data
members should be private</a>.</p>
-<p>Explicitly annotate overrides of virtual functions
-or virtual destructors with an <code>override</code>
-or (less frequently) <code>final</code> specifier.
-Older (pre-C++11) code will use the
-<code>virtual</code> keyword as an inferior
-alternative annotation. For clarity, use exactly one of
-<code>override</code>, <code>final</code>, or
-<code>virtual</code> when declaring an override.
+<p>Explicitly annotate overrides of virtual functions or virtual
+destructors with exactly one of an <code>override</code> or (less
+frequently) <code>final</code> specifier. Do not
+use <code>virtual</code> when declaring an override.
Rationale: A function or destructor marked
<code>override</code> or <code>final</code> that is
not an override of a base class virtual function will
@@ -1594,14 +1811,20 @@
<div class="summary">
<p> Make data members <code>private</code>, unless they are
<code>static const</code> (and follow the <a href="#Constant_Names">
-naming convention for constants</a>). For technical
+naming convention for constants</a>).</p>
+</div>
+
+<div class="stylebody">
+
+<p>For technical
reasons, we allow data members of a test fixture class to
be <code>protected</code> when using
<a href="https://github.com/google/googletest">Google
Test</a>).</p>
-</div>
+
+</div>
<h3 id="Declaration_Order">Declaration Order</h3>
@@ -1634,24 +1857,33 @@
<h2 id="Functions">Functions</h2>
-<h3 id="Function_Parameter_Ordering">Parameter Ordering</h3>
+<a id="Function_Parameter_Ordering"></a>
+<h3 id="Output_Parameters">Output Parameters</h3>
<div class="summary">
-<p>When defining a function, parameter order is: inputs, then
-outputs.</p>
+<p>Prefer using return values rather than output parameters.
+If output-only parameters are used they should appear after
+input parameters.</p>
</div>
<div class="stylebody">
-<p>Parameters to C/C++ functions are either input to the
-function, output from the function, or both. Input
-parameters are usually values or <code>const</code>
-references, while output and input/output parameters will
-be pointers to non-<code>const</code>. When ordering
-function parameters, put all input-only parameters before
-any output parameters. In particular, do not add new
-parameters to the end of the function just because they
-are new; place new input-only parameters before the
-output parameters.</p>
+<p>The output of a C++ function is naturally provided via
+a return value and sometimes via output parameters.</p>
+
+<p>Prefer using return values instead of output parameters
+since they improve readability and oftentimes provide the same
+or better performance.</p>
+
+<p>Parameters are either input to the function, output from the
+function, or both. Input parameters are usually values or
+<code>const</code> references, while output and input/output
+parameters will be pointers to non-<code>const</code>.</p>
+
+<p>When ordering function parameters, put all input-only
+parameters before any output parameters. In particular,
+do not add new parameters to the end of the function just
+because they are new; place new input-only parameters before
+the output parameters.</p>
<p>This is not a hard-and-fast rule. Parameters that are
both input and output (often classes/structs) muddy the
@@ -1773,7 +2005,9 @@
<div class="definition">
<p>You may write a function that takes a <code>const
string&</code> and overload it with another that
-takes <code>const char*</code>.</p>
+takes <code>const char*</code>. However, in this case consider
+std::string_view
+ instead.</p>
<pre>class MyClass {
public:
@@ -1800,13 +2034,13 @@
</div>
<div class="decision">
-<p>If you want to overload a function, consider qualifying
-the name with some information about the arguments, e.g.,
-<code>AppendString()</code>, <code>AppendInt()</code>
-rather than just <code>Append()</code>. If you are
-overloading a function to support variable number of
-arguments of the same type, consider making it take a
-<code>std::vector</code> so that the user can use an
+<p>You may overload a function when there are no semantic
+differences between variants, or when the differences are
+clear at the callsite.</p>
+
+<p>If you are overloading a function to support variable
+number of arguments of the same type, consider making it
+take a <code>std::vector</code> so that the user can use an
<a href="#Braced_Initializer_List">initializer list
</a> to specify the arguments.</p>
</div>
@@ -1907,9 +2141,13 @@
after the function's parameter list has already appeared. This is
particularly true when the return type depends on template parameters.
For example:</p>
- <pre>template <class T, class U> auto add(T t, U u) -> decltype(t + u);</pre>
+ <pre> template <typename T, typename U>
+ auto add(T t, U u) -> decltype(t + u);
+ </pre>
versus
- <pre>template <class T, class U> decltype(declval<T&>() + declval<U&>()) add(T t, U u);</pre>
+ <pre> template <typename T, typename U>
+ decltype(declval<T&>() + declval<U&>()) add(T t, U u);
+ </pre>
</div>
<div class="cons">
@@ -2085,8 +2323,7 @@
<h3 id="cpplint">cpplint</h3>
<div class="summary">
-<p>Use <code>cpplint.py</code>
-to detect style errors.</p>
+<p>Use <code>cpplint.py</code> to detect style errors.</p>
</div>
<div class="stylebody">
@@ -2322,13 +2559,107 @@
Things would probably be different if we had to do it all
over again from scratch.</p>
-<p>This prohibition also applies to the exception-related
-features added in C++11, such as <code>noexcept</code>,
-<code>std::exception_ptr</code>, and
+<p>This prohibition also applies to the exception handling related
+features added in C++11, such as
+<code>std::exception_ptr</code> and
<code>std::nested_exception</code>.</p>
<p>There is an <a href="#Windows_Code">exception</a> to
this rule (no pun intended) for Windows code.</p>
+
+</div>
+
+</div>
+
+<h3 id="noexcept"><code>noexcept</code></h3>
+
+<div class="summary">
+<p>Specify <code>noexcept</code> when it is useful and correct.</p>
+</div>
+
+<div class="stylebody">
+<div class="definition">
+<p>The <code>noexcept</code> specifier is used to specify whether
+a function will throw exceptions or not. If an exception
+escapes from a function marked <code>noexcept</code>, the program
+crashes via <code>std::terminate</code>.</p>
+
+<p>The <code>noexcept</code> operator performs a compile-time
+check that returns true if an expression is declared to not
+throw any exceptions.</p>
+
+</div>
+
+<div class="pros">
+<ul>
+ <li>Specifying move constructors as <code>noexcept</code>
+ improves performance in some cases, e.g.
+ <code>std::vector<T>::resize()</code> moves rather than
+ copies the objects if T's move constructor is
+ <code>noexcept</code>.</li>
+
+ <li>Specifying <code>noexcept</code> on a function can
+ trigger compiler optimizations in environments where
+ exceptions are enabled, e.g. compiler does not have to
+ generate extra code for stack-unwinding, if it knows
+ that no exceptions can be thrown due to a
+ <code>noexcept</code> specifier.</li>
+</ul>
+</div>
+
+<div class="cons">
+<ul>
+ <li>
+
+ In projects following this guide
+ that have exceptions disabled it is hard
+ to ensure that <code>noexcept</code>
+ specifiers are correct, and hard to define what
+ correctness even means.</li>
+
+ <li>It's hard, if not impossible, to undo <code>noexcept</code>
+ because it eliminates a guarantee that callers may be relying
+ on, in ways that are hard to detect.</li>
+</ul>
+</div>
+
+<div class="decision">
+<p>You may use <code>noexcept</code> when it is useful for
+performance if it accurately reflects the intended semantics
+of your function, i.e. that if an exception is somehow thrown
+from within the function body then it represents a fatal error.
+You can assume that <code>noexcept</code> on move constructors
+has a meaningful performance benefit. If you think
+there is significant performance benefit from specifying
+<code>noexcept</code> on some other function, please discuss it
+with
+your project leads.</p>
+
+<p>Prefer unconditional <code>noexcept</code> if exceptions are
+completely disabled (i.e. most Google C++ environments).
+Otherwise, use conditional <code>noexcept</code> specifiers
+with simple conditions, in ways that evaluate false only in
+the few cases where the function could potentially throw.
+The tests might include type traits check on whether the
+involved operation might throw (e.g.
+<code>std::is_nothrow_move_constructible</code> for
+move-constructing objects), or on whether allocation can throw
+(e.g. <code>absl::default_allocator_is_nothrow</code> for
+standard default allocation). Note in many cases the only
+possible cause for an exception is allocation failure (we
+believe move constructors should not throw except due to
+allocation failure), and there are many applications where it’s
+appropriate to treat memory exhaustion as a fatal error rather
+than an exceptional condition that your program should attempt
+to recover from. Even for other
+potential failures you should prioritize interface simplicity
+over supporting all possible exception throwing scenarios:
+instead of writing a complicated <code>noexcept</code> clause
+that depends on whether a hash function can throw, for example,
+simply document that your component doesn’t support hash
+functions throwing and make it unconditionally
+<code>noexcept</code>.</p>
+
</div>
</div>
@@ -2380,7 +2711,7 @@
<pre>bool Base::Equal(Base* other) = 0;
bool Derived::Equal(Base* other) {
Derived* that = dynamic_cast<Derived*>(other);
- if (that == NULL)
+ if (that == nullptr)
return false;
...
}
@@ -2519,7 +2850,9 @@
<div class="summary">
<p>Use streams where appropriate, and stick to "simple"
-usages.</p>
+usages. Overload <code><<</code> for streaming only for types
+representing values, and write only the user-visible value, not any
+implementation details.</p>
</div>
<div class="stylebody">
@@ -2576,12 +2909,7 @@
<li>The streams API is subtle and complex, so programmers must
-develop experience with it in order to use it effectively.
-However, streams were historically banned in Google code (except
-for logging and diagnostics), so Google engineers tend not to
-have that experience. Consequently, streams-based code is likely
-to be less readable and maintainable by Googlers than code based
-on more familiar abstractions.</li>
+develop experience with it in order to use it effectively.</li>
<li>Resolving the many overloads of <code><<</code> is
extremely costly for the compiler. When used pervasively in a
@@ -2834,8 +3162,9 @@
<div class="stylebody">
<div class="definition">
-<p> C++ does not specify the sizes of its integer types.
-Typically people assume that <code>short</code> is 16 bits,
+<p> C++ does not specify the sizes of integer types
+like <code>int</code>. Typically people assume
+that <code>short</code> is 16 bits,
<code>int</code> is 32 bits, <code>long</code> is 32 bits
and <code>long long</code> is 64 bits.</p>
</div>
@@ -2894,35 +3223,32 @@
usage of your container. When in doubt, use a larger type
rather than a smaller type.</p>
-<p>Use care when converting integer types. Integer
-conversions and promotions can cause non-intuitive
-behavior. </p>
+<p>Use care when converting integer types. Integer conversions and
+promotions can cause undefined behavior, leading to security bugs and
+other problems.</p>
</div>
<div class="stylepoint_subsection">
<h4>On Unsigned Integers</h4>
-<p>Some people, including some textbook authors,
-recommend using unsigned types to represent numbers that
-are never negative. This is intended as a form of
-self-documentation. However, in C, the advantages of such
-documentation are outweighed by the real bugs it can
-introduce. Consider:</p>
+<p>Unsigned integers are good for representing bitfields and modular
+arithmetic. Because of historical accident, the C++ standard also uses
+unsigned integers to represent the size of containers - many members
+of the standards body believe this to be a mistake, but it is
+effectively impossible to fix at this point. The fact that unsigned
+arithmetic doesn't model the behavior of a simple integer, but is
+instead defined by the standard to model modular arithmetic (wrapping
+around on overflow/underflow), means that a significant class of bugs
+cannot be diagnosed by the compiler. In other cases, the defined
+behavior impedes optimization.</p>
-<pre>for (unsigned int i = foo.Length()-1; i >= 0; --i) ...
-</pre>
-
-<p>This code will never terminate! Sometimes gcc will
-notice this bug and warn you, but often it will not.
-Equally bad bugs can occur when comparing signed and
-unsigned variables. Basically, C's type-promotion scheme
-causes unsigned types to behave differently than one
-might expect.</p>
-
-<p>So, document that a variable is non-negative using
-assertions. Don't use an unsigned
-type.</p>
+<p>That said, mixing signedness of integer types is responsible for an
+equally large class of problems. The best advice we can provide: try
+to use iterators and containers rather than pointers and sizes, try
+not to mix signedness, and try to avoid unsigned types (except for
+representing bitfields or modular arithmetic). Do not use an unsigned
+type merely to assert that a variable is non-negative.</p>
</div>
</div>
@@ -2938,109 +3264,27 @@
<ul>
<li>
- <p><code>printf()</code> specifiers for some types
- are not cleanly portable between 32-bit and 64-bit
- systems. C99 defines some portable format specifiers.
- Unfortunately, MSVC 7.1 does not understand some of
- these specifiers and the standard is missing a few,
- so we
- have to define our own ugly versions in some cases
- (in the style of the standard include file
- <code>inttypes.h</code>):</p>
-
- <div>
- <pre>// printf macros for size_t, in the style of inttypes.h
-#ifdef _LP64
-#define __PRIS_PREFIX "z"
-#else
-#define __PRIS_PREFIX
-#endif
-
-// Use these macros after a % in a printf format string
-// to get correct 32/64 bit behavior, like this:
-// size_t size = records.size();
-// printf("%" PRIuS "\n", size);
-
-#define PRIdS __PRIS_PREFIX "d"
-#define PRIxS __PRIS_PREFIX "x"
-#define PRIuS __PRIS_PREFIX "u"
-#define PRIXS __PRIS_PREFIX "X"
-#define PRIoS __PRIS_PREFIX "o"
- </pre>
- </div>
-
- <table border="1" summary="portable printf specifiers">
- <tbody><tr align="center">
- <th>Type</th>
- <th>DO NOT use</th>
- <th>DO use</th>
- <th>Notes</th>
- </tr>
-
- <tr align="center">
- <td><code>void *</code> (or any pointer)</td>
- <td><code>%lx</code></td>
- <td><code>%p</code></td>
- <td></td>
- </tr>
-
+ <p>Correct portable <code>printf()</code> conversion specifiers for
+ some integral typedefs rely on macro expansions that we find unpleasant to
+ use and impractical to require (the <code>PRI</code> macros from
+ <code><cinttypes></code>). Unless there is no reasonable alternative
+ for your particular case, try to avoid or even upgrade APIs that rely on the
+ <code>printf</code> family. Instead use a library supporting typesafe numeric
+ formatting, such as
+ <a href="#Streams"><code>std::ostream</code></a>.</p>
- <tr align="center">
- <td><code>int64_t</code></td>
- <td><code>%qd</code>, <code>%lld</code></td>
- <td><code>%" PRId64 "</code></td>
- <td></td>
- </tr>
-
+ <p>Unfortunately, the <code>PRI</code> macros are the only portable way to
+ specify a conversion for the standard bitwidth typedefs (e.g.
+ <code>int64_t</code>, <code>uint64_t</code>, <code>int32_t</code>,
+ <code>uint32_t</code>, etc).
-
- <tr align="center">
- <td><code>uint64_t</code></td>
- <td><code>%qu</code>, <code>%llu</code>,
- <code>%llx</code></td>
- <td><code>%" PRIu64 "</code>,
- <code>%" PRIx64 "</code></td>
- <td></td>
- </tr>
-
-
-
- <tr align="center">
- <td><code>size_t</code></td>
- <td><code>%u</code></td>
- <td><code>%" PRIuS "</code>, <code>%" PRIxS "</code></td>
- <td>
- C99 specifies <code>%zu</code></td>
- </tr>
-
- <tr align="center">
- <td><code>ptrdiff_t</code></td>
- <td><code>%d</code></td>
- <td><code>%" PRIdS "</code></td>
- <td>
- C99 specifies <code>%td</code></td>
- </tr>
-
-
- </tbody></table>
-
- <p>Note that the <code>PRI*</code> macros expand to
- independent strings which are concatenated by the
- compiler. Hence if you are using a non-constant
- format string, you need to insert the value of the
- macro into the format, rather than the name. Note also
- that spaces are required around the macro identifier to
- separate it from the string literal. It is
- still possible, as usual, to include length
- specifiers, etc., after the <code>%</code> when using
- the <code>PRI*</code> macros. So, e.g.
- <code>printf("x = %30" PRIuS "\n", x)</code> would
- expand on 32-bit Linux to <code>printf("x = %30" "u"
- "\n", x)</code>, which the compiler will treat as
- <code>printf("x = %30u\n", x)</code>.</p>
-
-
+ Where possible, avoid passing arguments of types specified by bitwidth
+ typedefs to <code>printf</code>-based APIs. Note that it is acceptable
+ to use typedefs for which printf has dedicated length modifiers, such as
+ <code>size_t</code> (<code>z</code>),
+ <code>ptrdiff_t</code> (<code>t</code>), and
+ <code>maxint_t</code> (<code>j</code>).</p>
</li>
<li>Remember that <code>sizeof(void *)</code> !=
@@ -3063,13 +3307,12 @@
<code>__declspec(align())</code>.</li>
<li>
- <p>Use the <code>LL</code> or <code>ULL</code>
- suffixes as needed to create 64-bit constants. For
- example:</p>
+ <p>Use <a href="#Casting">braced-initialization</a> as needed to create
+ 64-bit constants. For example:</p>
-<pre>int64_t my_value = 0x123456789LL;
-uint64_t my_mask = 3ULL << 48;
+<pre>int64_t my_value{0x123456789};
+uint64_t my_mask{3ULL << 48};
</pre>
</li>
</ul>
@@ -3168,30 +3411,25 @@
<h3 id="0_and_nullptr/NULL">0 and nullptr/NULL</h3>
<div class="summary">
-<p>Use <code>0</code> for integers, <code>0.0</code> for
-reals, <code>nullptr</code> (or <code>NULL</code>) for
-pointers, and <code>'\0'</code> for chars.</p>
+<p>Use <code>0</code> for integers, <code>0.0</code> for reals,
+<code>nullptr</code> for pointers, and <code>'\0'</code> for chars.</p>
</div>
<div class="stylebody">
-<p>Use <code>0</code> for integers and <code>0.0</code>
-for reals. This is not controversial.</p>
+<p>Use <code>0</code> for integers and <code>0.0</code> for reals.</p>
-<p> For
-pointers (address values), there is a choice between
-<code>0</code>, <code>NULL</code>, and
-<code>nullptr</code>. For projects that allow C++11
-features, use <code>nullptr</code>. For C++03 projects,
-we prefer <code>NULL</code> because it looks like a
-pointer. In fact, some C++ compilers provide special
-definitions of <code>NULL</code> which enable them to
-give useful warnings, particularly in situations where
-<code>sizeof(NULL)</code> is not equal to
-<code>sizeof(0)</code>.</p>
+<p>For pointers (address values), there is a choice between <code>0</code>,
+<code>NULL</code>, and <code>nullptr</code>. For projects that allow C++11
+features, use <code>nullptr</code>, as this provides type-safety.</p>
-<p>Use <code>'\0'</code> for chars. This is the correct
-type and also makes code more readable.</p>
+<p>For C++03 projects, prefer <code>NULL</code> to <code>0</code>. While the
+values are equivalent, <code>NULL</code> looks more like a pointer to the
+reader, and some C++ compilers provide special definitions of <code>NULL</code>
+which enable them to give useful warnings.</p>
+
+<p>Use <code>'\0'</code> for the null character. Using the correct type makes
+the code more readable.</p>
</div>
@@ -3241,8 +3479,8 @@
<div class="stylebody">
<div class="pros">
-<p>
-</p><ul>
+
+<ul>
<li>C++ type names can be long and cumbersome, especially when they
involve templates or namespaces.</li>
<li>When a C++ type name is repeated within a single declaration or a
@@ -3349,7 +3587,7 @@
std::vector<string> v = {"foo", "bar"};
// Usable with 'new' expressions.
-auto p = new vector<string>{"foo", "bar"};
+auto p = new std::vector<string>{"foo", "bar"};
// A map can take a list of pairs. Nested braced-init-lists work.
std::map<int, string> m = {{1, "one"}, {2, "2"}};
@@ -3938,7 +4176,8 @@
<code>Foo f = {.field = 3}</code>), inline assembly, <code>__COUNTER__</code>,
<code>__PRETTY_FUNCTION__</code>, compound statement expressions (e.g.
<code>foo = ({ int x; Bar(&x); x })</code>, variable-length arrays and
- <code>alloca()</code>, and the <code>a?:b</code> syntax.</p>
+ <code>alloca()</code>, and the "<a href="https://en.wikipedia.org/wiki/Elvis_operator">Elvis Operator</a>"
+ <code>a?:b</code>.</p>
</div>
<div class="pros">
@@ -3986,6 +4225,10 @@
using other_namespace::Foo;
</pre>
+ <p>In new code, <code>using</code> is preferable to <code>typedef</code>,
+ because it provides a more consistent syntax with the rest of C++ and works
+ with templates.</p>
+
<p>Like other declarations, aliases declared in a header file are part of that
header's public API unless they're in a function definition, in the private portion of a class,
or in an explicitly-marked internal namespace. Aliases in such areas or in .cc files are
@@ -4031,32 +4274,32 @@
</p>
<p>For example, these aliases document how they are intended to be used in client code:</p>
-<pre>namespace a {
+<pre>namespace mynamespace {
// Used to store field measurements. DataPoint may change from Bar* to some internal type.
// Client code should treat it as an opaque pointer.
-using DataPoint = foo::bar::Bar*;
+using DataPoint = foo::Bar*;
// A set of measurements. Just an alias for user convenience.
using TimeSeries = std::unordered_set<DataPoint, std::hash<DataPoint>, DataPointComparator>;
-} // namespace a
+} // namespace mynamespace
</pre>
<p>These aliases don't document intended use, and half of them aren't meant for client use:</p>
-<pre class="badcode">namespace a {
+<pre class="badcode">namespace mynamespace {
// Bad: none of these say how they should be used.
-using DataPoint = foo::bar::Bar*;
+using DataPoint = foo::Bar*;
using std::unordered_set; // Bad: just for local convenience
using std::hash; // Bad: just for local convenience
typedef unordered_set<DataPoint, hash<DataPoint>, DataPointComparator> TimeSeries;
-} // namespace a
+} // namespace mynamespace
</pre>
<p>However, local convenience aliases are fine in function definitions, private sections of
classes, explicitly marked internal namespaces, and in .cc files:</p>
<pre>// In a .cc file
-using std::unordered_set;
+using foo::Bar;
</pre>
</div>
@@ -4091,11 +4334,17 @@
understandable by a new reader. Do not use abbreviations
that are ambiguous or unfamiliar to readers outside your
project, and do not abbreviate by deleting letters within
-a word.</p>
+a word. Abbreviations that would be familiar to someone
+outside your project with relevant domain knowledge are OK.
+As a rule of thumb, an abbreviation is probably OK if it's listed
+in
+
+Wikipedia.</p>
<pre>int price_count_reader; // No abbreviation.
int num_errors; // "num" is a widespread convention.
int num_dns_connections; // Most people know what "DNS" stands for.
+int lstm_size; // "LSTM" is a common machine learning abbreviation.
</pre>
<pre class="badcode">int n; // Meaningless.
@@ -4104,12 +4353,20 @@
int wgc_connections; // Only your group knows what this stands for.
int pc_reader; // Lots of things can be abbreviated "pc".
int cstmr_id; // Deletes internal letters.
+FooBarRequestInfo fbri; // Not even a word.
</pre>
<p>Note that certain universally-known abbreviations are OK, such as
<code>i</code> for an iteration variable and <code>T</code> for a
template parameter.</p>
+<p>For some symbols, this style guide recommends names to start with a capital
+letter and to have a capital letter for each new word (a.k.a.
+"<a href="https://en.wikipedia.org/wiki/Camel_case">Camel Case</a>"
+or "Pascal case"). When abbreviations appear in such names, prefer to
+capitalize the abbreviations as single words (i.e. <code>StartRpc()</code>,
+not <code>StartRPC()</code>).</p>
+
<p>Template parameters should follow the naming style for their
category: type template parameters should follow the rules for
<a href="#Type_Names">type names</a>, and non-type template
@@ -4268,9 +4525,9 @@
see <a href="http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration">
Storage Duration</a> for details) should be named this way. This
convention is optional for variables of other storage classes, e.g. automatic
- variables, otherwise the usual variable naming rules apply.</p><p>
+ variables, otherwise the usual variable naming rules apply.</p>
-</p></div>
+</div>
<h3 id="Function_Names">Function Names</h3>
@@ -4282,11 +4539,7 @@
<div class="stylebody">
<p>Ordinarily, functions should start with a capital letter and have a
-capital letter for each new word
-(a.k.a. "<a href="https://en.wikipedia.org/wiki/Camel_case">Camel
-Case</a>" or "Pascal case"). Such names should not have
-underscores. Prefer to capitalize acronyms as single words
-(i.e. <code>StartRpc()</code>, not <code>StartRPC()</code>).</p>
+capital letter for each new word.</p>
<pre>AddTableEntry()
DeleteUrl()
@@ -4295,8 +4548,8 @@
<p>(The same naming rule applies to class- and namespace-scope
constants that are exposed as part of an API and that are intended to look
-like functions, because the fact that they're
-objects rather than functions is an unimportant implementation detail.)</p>
+like functions, because the fact that they're objects rather than functions
+is an unimportant implementation detail.)</p>
<p>Accessors and mutators (get and set functions) may be named like
variables. These often correspond to actual member variables, but this is
@@ -4318,7 +4571,7 @@
<p>The name of a top-level namespace should usually be the
name of the project or team whose code is contained in that
namespace. The code in that namespace should usually be in
-a directory whose basename matches the namespace name (or
+a directory whose basename matches the namespace name (or in
subdirectories thereof).</p>
@@ -4398,7 +4651,8 @@
<div class="summary">
<p>You're not really going to <a href="#Preprocessor_Macros">
define a macro</a>, are you? If you do, they're like this:
-<code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN</code>.</p>
+<code>MY_MACRO_THAT_SCARES_SMALL_CHILDREN_AND_ADULTS_ALIKE</code>.
+</p>
</div>
<div class="stylebody">
@@ -4500,7 +4754,9 @@
BSD, LGPL, GPL).</p>
<p>If you make significant changes to a file with an
-author line, consider deleting the author line.</p>
+author line, consider deleting the author line.
+New files should usually not contain copyright notice or
+author line.</p>
<h4 class="stylepoint_subsection">File Contents</h4>
@@ -4619,13 +4875,7 @@
</pre>
<p>However, do not be unnecessarily verbose or state the
-completely obvious. Notice below that it is not necessary
- to say "returns false otherwise" because this is
-implied.</p>
-
-<pre>// Returns true if the table cannot hold any more entries.
-bool IsTableFull();
-</pre>
+completely obvious.</p>
<p>When documenting function overrides, focus on the
specifics of the override itself, rather than repeating
@@ -4791,7 +5041,7 @@
<li>Replace large or complex nested expressions with named variables.</li>
<li>As a last resort, use comments to clarify argument meanings at the
- call site.</li>
+ call site. </li>
</ul>
Consider the following example:
@@ -5135,8 +5385,8 @@
<ul>
<li>Choose good parameter names.</li>
- <li>Parameter names may be omitted only if the parameter is unused and its
- purpose is obvious.</li>
+ <li>A parameter name may be omitted only if the parameter is not used in the
+ function's definition.</li>
<li>If you cannot fit the return type and the function
name on a single line, break between them.</li>
@@ -5429,7 +5679,7 @@
conditions or statements may be more readable with curly
braces. Some
projects require that an
-<code>if</code> must always always have an accompanying
+<code>if</code> must always have an accompanying
brace.</p>
<pre>if (condition)
@@ -5475,7 +5725,7 @@
<p>Switch statements may use braces for blocks. Annotate
non-trivial fall-through between cases.
Braces are optional for single-statement loops.
-Empty loop bodies should use empty braces or <code>continue</code>.</p>
+Empty loop bodies should use either empty braces or <code>continue</code>.</p>
</div>
<div class="stylebody">
@@ -5489,10 +5739,9 @@
statements should always have a <code>default</code> case
(in the case of an enumerated value, the compiler will
warn you if any values are not handled). If the default
-case should never execute, simply
-<code>assert</code>:</p>
+case should never execute, treat this as an error. For example:
-
+</p>
<div>
<pre>switch (var) {
@@ -5526,8 +5775,8 @@
</pre>
-<p>Empty loop bodies should use an empty pair of braces or <code>continue</code>,
-but not a single semicolon.</p>
+<p>Empty loop bodies should use either an empty pair of braces or
+<code>continue</code> with no braces, rather than a single semicolon.</p>
<pre>while (condition) {
// Repeat test until it returns false.
@@ -5582,6 +5831,11 @@
const string& str;
</pre>
+<p>You should do this consistently within a single
+file,
+so, when modifying an existing file, use the style in
+that file.</p>
+
It is allowed (if unusual) to declare multiple variables in the same
declaration, but it is disallowed if any of those have pointer or
reference decorations. Such declarations are easily misread.
@@ -5593,11 +5847,6 @@
const string & str; // Bad - spaces on both sides of &
</pre>
-<p>You should do this consistently within a single
-file,
-so, when modifying an existing file, use the style in
-that file.</p>
-
</div>
<h3 id="Boolean_Expressions">Boolean Expressions</h3>
@@ -5691,8 +5940,8 @@
non-<code>std::initializer_list</code> constructor, use parentheses
instead of braces.</p>
-<pre>std::vector<int> v(100, 1); // A vector of 100 1s.
-std::vector<int> v{100, 1}; // A vector of 100, 1.
+<pre>std::vector<int> v(100, 1); // A vector containing 100 items: All 1s.
+std::vector<int> v{100, 1}; // A vector containing 2 items: 100 and 1.
</pre>
<p>Also, the brace form prevents narrowing of integral
@@ -5867,7 +6116,7 @@
<pre class="badcode">namespace {
- // Wrong. Indented when it should not be.
+ // Wrong! Indented when it should not be.
void foo() {
...
}
@@ -6138,7 +6387,7 @@
</div>
-<h2 class="ignoreLink">Parting Words</h2>
+<h2 id="Parting_Words">Parting Words</h2>
<p>Use common sense and <em>BE CONSISTENT</em>.</p>
