Update C++ style guide

2024-03-22 13:11:43 +08:00 · 2018-07-31 10:17:48 -07:00 · 2018-07-31 10:17:48 -07:00 · b89a775fa7
commit b89a775fa7
parent ab48617e00
1 changed files with 143 additions and 202 deletions
--- a/cppguide.html
+++ b/cppguide.html
@ -10,8 +10,6 @@
 <body onload="initStyleGuide();">
 <div id="content">
 <h1>Google C++ Style Guide</h1>
 <div class="horizontal_toc" id="tocDiv"></div>
 <div class="main_body">
 <h2 class="ignoreLink" id="Background">Background</h2>
@ -162,6 +160,22 @@ input.</p>
 <h2 id="C++_Version">C++ Version</h2>
 <p>
 Currently, code should target C++11, i.e., should not use C++14 or
 C++17 features. The C++ version targeted by this guide will advance
 (aggressively) over time.</p>
 <p>
 Code should avoid features that have been removed from
 the latest language version (currently C++17), as well as the rare
 cases where code has a different meaning in that latest version.
 Use of some C++ features is restricted or disallowed.  Do not use
 <a href="#Nonstandard_Extensions">non-standard extensions</a>.</p>
 <h2 id="Header_Files">Header Files</h2>
 <p>In general, every <code>.cc</code> file should have an
@ -972,10 +986,12 @@ 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!
+<pre class="badcode">// Some declarations used below.
 time_t time(time_t*);      // not constexpr!
 int f();                   // not constexpr!
 struct Bar { Bar() {} };
 // Problematic initializations.
 time_t m = time(nullptr);  // initializing expression not a constant expression
 Foo y(f());                // ditto
 Bar b;                     // chosen constructor Bar::Bar() not constexpr</pre>
@ -1514,6 +1530,7 @@ functors and traits.</p>
 </div> 
 <a id="Multiple_Inheritance"></a>
 <h3 id="Inheritance">Inheritance</h3>
 <div class="summary">
@ -1522,16 +1539,14 @@ When using inheritance, make it <code>public</code>.</p>
 </div>
 <div class="stylebody">
 <div class="definition">
 <p> When a sub-class
 inherits from a base class, it includes the definitions
-of all the data and operations that the parent base class
+of all the data and operations that the base class
-defines. In practice, inheritance is used in two major
+defines. "Interface inheritance" is inheritance from a
-ways in C++: implementation inheritance, in which actual
+pure abstract base class (one with no state or defined
-code is inherited by the child, and
+methods); all other inheritance is "implementation
-<a href="#Interfaces">interface inheritance</a>, in which
+inheritance".</p>
 only method names are inherited.</p>
 </div>
 <div class="pros">
@ -1553,6 +1568,14 @@ 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.</p>
 <p>Multiple inheritance is especially problematic, because
 it often imposes a higher performance overhead (in fact,
 the performance drop from single inheritance to multiple
 inheritance can often be greater than the performance
 drop from ordinary to virtual dispatch), and because
 it risks leading to "diamond" inheritance patterns,
 which are prone to ambiguity, confusion, and outright bugs.</p>
 </div>
 <div class="decision">
@ -1585,119 +1608,9 @@ specifiers serve as documentation; if no specifier is
 present, the reader has to check all ancestors of the
 class in question to determine if the function or
 destructor is virtual or not.</p>
 </div>
-</div> 
+  <p>Multiple inheritance is permitted, but multiple <em>implementation</em>
-
+inheritance is strongly discouraged.</p>
 <h3 id="Multiple_Inheritance">Multiple Inheritance</h3>
 <div class="summary">
 <p>Only very rarely is multiple implementation inheritance
 actually useful. We allow multiple inheritance only when at
 most one of the base classes has an implementation; all
 other base classes must be <a href="#Interfaces">pure
 interface</a> classes tagged with the
 <code>Interface</code> suffix.</p>
 </div>
 <div class="stylebody">
 <div class="definition">
 <p>Multiple inheritance allows a sub-class to have more than
 one base class. We distinguish between base classes that are
 <em>pure interfaces</em> and those that have an
 <em>implementation</em>.</p>
 </div>
 <div class="pros">
 <p>Multiple implementation inheritance may let you re-use
 even more code than single inheritance (see <a href="#Inheritance">Inheritance</a>).</p>
 </div>
 <div class="cons">
 <p>Only very rarely is multiple <em>implementation</em>
 inheritance actually useful. When multiple implementation
 inheritance seems like the solution, you can usually find
 a different, more explicit, and cleaner solution.</p>
 </div>
 <div class="decision">
 <p> Multiple inheritance is allowed only when all
 superclasses, with the possible exception of the first one,
 are <a href="#Interfaces">pure interfaces</a>. In order to
 ensure that they remain pure interfaces, they must end with
 the <code>Interface</code> suffix.</p>
 </div>
 <div class="note">
 <p>There is an <a href="#Windows_Code">exception</a> to
 this rule on Windows.</p>
 </div>
 </div> 
 <h3 id="Interfaces">Interfaces</h3>
 <div class="summary">
 <p>Classes that satisfy certain conditions are allowed, but
 not required, to end with an <code>Interface</code> suffix.</p>
 </div>
 <div class="stylebody">
 <div class="definition">
 <p>A class is a pure interface if it meets the following
 requirements:</p>
 <ul>
  <li>It has only public pure virtual ("<code>=
  0</code>") methods and static methods (but see below
  for destructor).</li>
  <li>It may not have non-static data members.</li>
  <li>It need not have any constructors defined. If a
  constructor is provided, it must take no arguments and
  it must be protected.</li>
  <li>If it is a subclass, it may only be derived from
  classes that satisfy these conditions and are tagged
  with the <code>Interface</code> suffix.</li>
 </ul>
 <p>An interface class can never be directly instantiated
 because of the pure virtual method(s) it declares. To
 make sure all implementations of the interface can be
 destroyed correctly, the interface must also declare a
 virtual destructor (in an exception to the first rule,
 this should not be pure). See Stroustrup, <cite>The C++
 Programming Language</cite>, 3rd edition, section 12.4
 for details.</p>
 </div>
 <div class="pros">
 <p>Tagging a class with the <code>Interface</code> suffix
 lets others know that they must not add implemented
 methods or non static data members. This is particularly
 important in the case of <a href="#Multiple_Inheritance">multiple inheritance</a>.
 Additionally, the interface concept is already
 well-understood by Java programmers.</p>
 </div>
 <div class="cons">
 <p>The <code>Interface</code> suffix lengthens the class
 name, which can make it harder to read and understand.
 Also, the interface property may be considered an
 implementation detail that shouldn't be exposed to
 clients.</p>
 </div>
 <div class="decision">
 <p>A class may end
 with <code>Interface</code> only if it meets the above
 requirements. We do not require the converse, however:
 classes that meet the above requirements are not required
 to end with <code>Interface</code>.</p>
 </div>
 </div> 
@ -1840,7 +1753,7 @@ apply to operator overloading as well.</p>
 <h3 id="Access_Control">Access Control</h3>
 <div class="summary">
-<p> Make data members <code>private</code>, unless they are
+<p>Make classes' data members <code>private</code>, unless they are
 <code>static const</code> (and follow the <a href="#Constant_Names">
 naming convention for constants</a>).</p>
 </div>
@ -1848,7 +1761,7 @@ naming convention for constants</a>).</p>
 <div class="stylebody">
 <p>For technical
-reasons, we allow data members of a test fixture class to
+reasons, we allow data members of a test fixture class in a .cc file to
 be <code>protected</code> when using
@ -1956,7 +1869,7 @@ the function into smaller and more manageable pieces.</p>
 <h3 id="Reference_Arguments">Reference Arguments</h3>
 <div class="summary">
-<p>All parameters passed by reference must be labeled
+<p>All parameters passed by lvalue reference must be labeled
 <code>const</code>.</p>
 </div>
@ -2053,6 +1966,11 @@ std::string_view
 identically-named function to take different arguments.
 It may be necessary for templatized code, and it can be
 convenient for Visitors.</p>
 <p>Overloading based on const or ref qualification may make utility
  code more usable, more efficient, or both.
  (See <a href="http://abseil.io/tips/148">TotW 148</a> for more.)
 </p>
 </div>
 <div class="cons">
@ -2065,15 +1983,13 @@ function.</p>
 </div>
 <div class="decision">
-<p>You may overload a function when there are no semantic
+<p>You may overload a function when there are no semantic differences
-differences between variants, or when the differences are
+between variants. These overloads may vary in types, qualifiers, or
-clear at the callsite.</p>
+argument count. However, a reader of such a call must not need to know
-
+which member of the overload set is chosen, only that <b>something</b>
-<p>If you are overloading a function to support variable
+from the set is being called. If you can document all entries in the
-number of arguments of the same type, consider making it
+overload set with a single comment in the header, that is a good sign
-take a <code>std::vector</code> so that the user can use an
+that it is a well-designed overload set.</p>
 <a href="#Braced_Initializer_List">initializer list
 </a> to specify the arguments.</p>
 </div>
 </div> 
@ -2183,7 +2099,7 @@ doubt, use overloads.</p>
 <div class="cons">
 <p>Trailing return type syntax is relatively new and it has no
-  analogue in C++-like languages like C and Java, so some readers may
+  analogue in C++-like languages such as C and Java, so some readers may
  find it unfamiliar.</p>
 <p>Existing code bases have an enormous number of function
  declarations that aren't going to get changed to use the new syntax,
@ -2385,9 +2301,19 @@ you can download
 <h3 id="Rvalue_references">Rvalue References</h3>
 <div class="summary">
-<p>Use rvalue references only to define move constructors and move assignment
+<p>Use rvalue references to:</p>
-operators, or for perfect forwarding.
+<ul>
-</p>
+  <li>Define move constructors and move assignment operators.</li>
  <li>Define <a href="#Function_Overloading">overload sets</a> with
  const&amp; and &amp;&amp; variants if you have evidence that this
  provides meaningfully better performance than passing by value,
  or if you're writing low-overhead generic code that needs to support
  arbitrary types. Beware combinatorial overload sets, that is, seldom
  overload more than one parameter.</li>
  <li>Support 'perfect forwarding' in generic code.</li>
 </ul>
 </div>
 <div class="stylebody">
@ -2399,6 +2325,11 @@ objects. The syntax is similar to traditional reference
 syntax. For example, <code>void f(string&amp;&amp;
 s);</code> declares a function whose argument is an
 rvalue reference to a string.</p>
 <p id="Forwarding_references"> When the token '&amp;&amp;' is applied to
 an unqualified template argument in a function
 parameter, special template argument deduction
 rules apply. Such a reference is called forwarding reference.</p>
 </div>
 <div class="pros">
@ -2410,15 +2341,9 @@ rvalue reference to a string.</p>
  for example, then <code>auto v2(std::move(v1))</code>
  will probably just result in some simple pointer
  manipulation instead of copying a large amount of data.
-  In some cases this can result in a major performance
+  In many cases this can result in a major performance
  improvement.</li>
  <li>Rvalue references make it possible to write a
  generic function wrapper that forwards its arguments to
  another function, and works whether or not its
  arguments are temporary objects. (This is sometimes called
  "perfect forwarding".)</li>
  <li>Rvalue references make it possible to implement
  types that are movable but not copyable, which can be
  useful for types that have no sensible definition of
@ -2428,25 +2353,45 @@ rvalue reference to a string.</p>
  <li><code>std::move</code> is necessary to make
  effective use of some standard-library types, such as
  <code>std::unique_ptr</code>.</li>
  <li><a href="#Forwarding_references">Forwarding references</a> which
  use the rvalue reference token, make it possible to write a
  generic function wrapper that forwards its arguments to
  another function, and works whether or not its
  arguments are temporary objects and/or const.
  This is called 'perfect forwarding'.</li>
 </ul>
 </div>
 <div class="cons">
 <ul>
-  <li>Rvalue references are a relatively new feature
+  <li>Rvalue references are not yet widely
-  (introduced as part of C++11), and not yet widely
+  understood. Rules like automatic synthesis of move constructors and reference
-  understood. Rules like reference collapsing, and
+  collapsing (the latter refers to the special rules that apply to a T&amp;&amp;
-  automatic synthesis of move constructors, are
+  parameter in a function template) are somewhat obscure.</li>
-  complicated.</li>
+
  <li>Rvalue references are often misused. Using rvalue
  references is counter-intuitive in signatures where the argument is expected
  to have a valid specified state after the function call, or where no move
  operation is performed.</li>
 </ul>
 </div>
 <div class="decision">
-  <p>Use rvalue references only to define move constructors and move assignment
+  <p>You may use rvalue references to define move constructors and move
-  operators (as described in <a href="#Copyable_Movable_Types">Copyable and
+  assignment operators (as described in <a href="#Copyable_Movable_Types">Copyable and Movable Types</a>). See the <a href="primer#copying_moving">C++ Primer</a> for more information about
-  Movable Types</a>) and, in conjunction with <code><a href="http://en.cppreference.com/w/cpp/utility/forward">std::forward</a></code>,
+  move semantics and <code>std::move</code>.</p>
-to support perfect forwarding.  You may use <code>std::move</code> to express
+
-moving a value from one object to another rather than copying it. </p>
+  <p>You may use rvalue references to define pairs of overloads, one taking
  Foo&amp;&amp; and the other taking const Foo&amp;. Usually the preferred
  solution is just to pass by value, but an overloaded pair of functions
  sometimes yields better performance and is sometimes necessary in generic code
  that needs to support a wide variety of types. As always: if you're writing
  more complicated code for the sake of performance, make sure you have evidence
  that it actually helps.</p>
  <p>You may use forwarding references in conjunction with <code><a href="http://en.cppreference.com/w/cpp/utility/forward">std::forward</a></code>,
  to support perfect forwarding.</p>
 </div>
 </div> 
@ -2957,6 +2902,7 @@ end-users. Be consistent with the code around you, and with the
 codebase as a whole; if there's an established tool for
 your problem, use that tool instead.
 In particular,
 logging libraries are usually a better
 choice than <code>std::cerr</code> or <code>std::clog</code>
 for diagnostic output, and the libraries in
@ -3467,9 +3413,8 @@ name (but upper case). </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>,
+<p>For pointers (address values), use <code>nullptr</code>, as this
-<code>NULL</code>, and <code>nullptr</code>. For projects that allow C++11
+provides type-safety.</p>
 features, use <code>nullptr</code>, as this provides type-safety.</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
@ -3830,9 +3775,6 @@ few variables for a short lambda, where the set of captured
 variables is obvious at a glance. Prefer not to write long or
 complex lambdas with default capture by value.
 </li>
 <li>Keep unnamed lambdas short.  If a lambda body is more than
 maybe five lines long, prefer to give the lambda a name, or to
 use a named function instead of a lambda.</li>
 <li>Specify the return type of the lambda explicitly if that will
 make it more obvious to readers, as with
 <a href="#auto"><code>auto</code></a>.</li>
@ -4147,7 +4089,7 @@ libraries. </p>
 </div>
 <div class="pros">
-<p>C++11 was the official standard until august 2014, and
+<p>C++11 was the official standard until 2014, and
 is supported by most C++ compilers. It standardizes
 some common C++ extensions that we use already, allows
 shorthands for some operations, and has some performance
@ -4200,10 +4142,6 @@ guide, the following C++11 features may not be used:</p>
  <code>&lt;fenv.h&gt;</code> headers, because many
  compilers do not support those features reliably.</li>
  <li>Ref-qualifiers on member functions, such as <code>void X::Foo()
    &amp;</code> or <code>void X::Foo() &amp;&amp;</code>, because of concerns
    that they're an overly obscure feature.</li>
@ -4412,9 +4350,9 @@ 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
+or "Pascal case"). When abbreviations or acronyms appear in such
-capitalize the abbreviations as single words (i.e. <code>StartRpc()</code>,
+names, prefer to capitalize the abbreviations or acronyms as single words (i.e
-not <code>StartRPC()</code>).</p>
+<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
@ -4461,10 +4399,6 @@ of files called, e.g., <code>foo_bar.h</code> and
 <code>foo_bar.cc</code>, defining a class called
 <code>FooBar</code>.</p>
 <p>Inline functions must be in a <code>.h</code> file. If
 your inline functions are very short, they should go
 directly into your <code>.h</code> file. </p>
 </div> 
 <h3 id="Type_Names">Type Names</h3>
@ -4562,10 +4496,12 @@ versus a class.</p>
 <div class="summary">
  <p>Variables declared constexpr or const, and whose value is fixed for
  the duration of the program, are named with a leading "k" followed
-  by mixed case.  For example:</p>
+  by mixed case. Underscores can be used as separators in the rare cases
  where capitalization cannot be used for separation. For example:</p>
 </div>
 <pre>const int kDaysInAWeek = 7;
 const int kAndroid8_0_0 = 24;  // Android 8.0.0
 </pre>
 <div class="stylebody">
@ -5018,7 +4954,7 @@ non-obvious, interesting, or important parts of your code.</p>
 <p>Tricky or complicated code blocks should have comments
 before them. Example:</p>
-<pre>// Divide result by two, taking into account that x
+<pre>// Divides result by two, taking into account that x
 // contains the carry from the add.
 for (int i = 0; i &lt; result-&gt;size(); i++) {
  x = (x &lt;&lt; 8) + (*result)[i];
@ -5061,7 +4997,7 @@ std::vector&lt;string&gt; list{
 DoSomething(); /* For trailing block comments, one space is fine. */
 </pre>
-<h4 class="stylepoint_subsection">Function Argument Comments</h4>
+<h4 class="stylepoint_subsection" id="Function_Argument_Comments">Function Argument Comments</h4>
 <p>When the meaning of a function argument is nonobvious, consider
 one of the following remedies:</p>
@ -5309,22 +5245,23 @@ can easily show longer lines.</p>
 <div class="decision">
 <p> 80 characters is the maximum.</p>
-<p class="exception">Comment lines can be longer than 80
+<p>A line may exceed 80 characters if it is</p>
 characters if it is not feasible to split them without
 harming readability, ease of cut and paste or auto-linking
 -- e.g. if a line contains an example command or a literal
 URL longer than 80 characters.</p>
-<p class="exception">A raw-string literal may have content
+<ul>
-that exceeds 80 characters.  Except for test code, such literals
+  <li>a comment line which is not feasible to split without harming
-should appear near the top of a file.</p>
+  readability, ease of cut and paste or auto-linking -- e.g. if a line
  contains an example command or a literal URL longer than 80 characters.</li>
-<p class="exception">An <code>#include</code> statement with a
+  <li>a raw-string literal with content that exceeds 80 characters.  Except for
-long path may exceed 80 columns.</p>
+  test code, such literals should appear near the top of a file.</li>
  <li>an include statement.</li>
  <li>a <a href="#The__define_Guard">header guard</a></li>
  <li>a using-declaration</li>
 </ul>
 <p class="exception">You needn't be concerned about
 <a href="#The__define_Guard">header guards</a> that exceed
 the maximum length. </p>
 </div>
 </div> 
@ -6316,29 +6253,33 @@ std::vector&lt;char *&gt; x;
 <div class="stylebody">
-<p>This is more a principle than a rule: don't use blank
+<p>This is more a principle than a rule: don't use blank lines when
-lines when you don't have to. In particular, don't put
+you don't have to. In particular, don't put more than one or two blank
-more than one or two blank lines between functions,
+lines between functions, resist starting functions with a blank line,
-resist starting functions with a blank line, don't end
+don't end functions with a blank line, and be sparing with your use of
-functions with a blank line, and be discriminating with
+blank lines. A blank line within a block of code serves like a
-your use of blank lines inside functions.</p>
+paragraph break in prose: visually separating two thoughts.</p>
-<p>The basic principle is: The more code that fits on one
+<p>The basic principle is: The more code that fits on one screen, the
-screen, the easier it is to follow and understand the
+easier it is to follow and understand the control flow of the
-control flow of the program. Of course, readability can
+program. Use whitespace purposefully to provide separation in that
-suffer from code being too dense as well as too spread
+flow.</p>
 out, so use your judgement. But in general, minimize use
 of vertical whitespace.</p>
 <p>Some rules of thumb to help when blank lines may be
 useful:</p>
 <ul>
  <li>Blank lines at the beginning or end of a function
-  very rarely help readability.</li>
+  do not help readability.</li>
  <li>Blank lines inside a chain of if-else blocks may
  well help readability.</li>
  <li>A blank line before a comment line usually helps
  readability &#8212; the introduction of a new comment suggests
  the start of a new thought, and the blank line makes it clear
  that the comment goes with the following thing instead of the
  preceding.</li>
 </ul>
 </div>