Lines Matching +full:d3 +full:- +full:hierarchy
4 <meta charset="utf-8">
19 many of Google's open-source projects. As every C++
22 code more bug-prone and harder to read and maintain.</p>
36 Most open-source projects developed by
79 particularly common sub-point of this principle: When something
105 prefer a homegrown or third-party library over a library defined in
169 <a href="#Nonstandard_Extensions">non-standard extensions</a>.</p>
189 <a id="The_-inl.h_Files"></a>
190 <h3 id="Self_contained_Headers">Self-contained Headers</h3>
192 <p>Header files should be self-contained (compile on their own) and
193 end in <code>.h</code>. Non-header files that are meant for inclusion
196 <p>All header files should be self-contained. Users and refactoring
208 definitions to separately included header files (<code>-inl.h</code>);
217 self-contained. These are typically intended to be included at unusual
221 extension. Use sparingly, and prefer self-contained headers when
282 otherwise-compatible changes to their APIs, such as
349 performance-critical functions.</p>
364 implicit member- and base-destructor calls!</p>
394 <code>google-awesome-project/src/base/logging.h</code>
431 <p>Separate each non-empty group with one blank line.</p>
468 <code>google-awesome-project/src/foo/internal/fooserver.cc</code>
486 <p>Sometimes, system-specific code needs
489 system-specific code small and localized. Example:</p>
506 its path. Do not use <i>using-directives</i> (e.g.
559 symbols by their fully-qualified names. For deeply-nested
603 like flags or using-declarations.</p>
625 <a href="https://developers.google.com/protocol-buffers/docs/reference/cpp-generated#package">
636 <li><p>You may not use a <i>using-directive</i>
639 <pre class="badcode">// Forbidden -- This pollutes the namespace.
646 internal-only namespaces, because anything imported into a namespace
747 i = f(); // Bad -- initialization separate from declaration.
750 <pre>int j = g(); // Good -- declaration has initialization.
758 <pre>std::vector<int> v = {1, 2}; // Good -- v starts initialized.
798 means that the type has no user-defined or virtual destructor and that all bases
799 and non-static members are trivially destructible.
800 Static function-local variables may use dynamic initialization.
813 function-local variables that are declared with the <code>static</code>
814 specifier. Function-local static variables are initialized when control first
816 are initialized as part of program start-up. All objects with static storage
821 non-trivial happens during initialization. (For example, consider a constructor
833 translation unit, command-line flags, logging, registration mechanisms,
838 non-trivial destructors create complexity that can easily lead to hard-to-find
869 <pre class="badcode">// bad: non-trivial destructor
873 // rule also applies to lifetime-extended temporary objects)
877 // bad: non-trivial destructor
883 applies, though. In particular, a function-local static reference of the form
916 <a href="https://github.com/abseil/abseil-cpp/blob/03c1513538584f4a04d666be5eb469e3979febba/absl/ba…
918 attribute. Any non-local static storage
956 since they have non-trivial destructors. Instead, consider a simple array of
962 …<a href="https://github.com/abseil/abseil-cpp/blob/master/absl/algorithm/container.h">absl/algorit…
967 container from the standard library, consider using a function-local static
978 it by using a function-local static pointer or reference (e.g. <code>static
985 must be initialized with a true compile-time constant,
989 <a href="https://github.com/abseil/abseil-cpp/blob/master/absl/base/attributes.h">
992 <code>thread_local</code> over other ways of defining thread-local data.</p>
1012 initialization-order issues as static variables (and more besides).</p>
1015 terminates, so they do not have the destruction-order issues of static
1020 <li>Thread-local data is inherently safe from races (because only one thread
1023 <li><code>thread_local</code> is the only standard-supported way of creating
1024 thread-local data.</li>
1033 thread-safety.</li>
1045 a function-scope <code>thread_local</code> to simulate a class- or
1046 namespace-scope <code>thread_local</code> by defining a function or
1056 initialized with a true compile-time constant (i.e. they must have no
1061 <a href="https://github.com/abseil/abseil-cpp/blob/master/absl/base/attributes.h">
1069 defining thread-local data.</p>
1128 (semi-constructed objects of this form are particularly hard to work
1135 keyword for conversion operators and single-argument
1188 <li>Implicit conversions can hide type-mismatch bugs, where the
1200 <li>When a single-argument constructor is not marked
1228 also omit <code>explicit</code>, in order to support copy-initialization
1235 move-only, or neither copyable nor movable. Support copying and/or
1253 <p>For user-defined types, the copy behavior is defined by the copy
1254 constructor and the copy-assignment operator. Move behavior is defined by the
1255 move constructor and the move-assignment operator, if they exist, or by the
1256 copy constructor and the copy-assignment operator otherwise.</p>
1266 contract. It also prevents non-local interactions between the client and the
1269 require pass-by-value, such as most containers, and they allow for additional
1298 Defaulted or carelessly-implemented copy operations can be incorrect, and the
1303 languages where pass-by-reference is conventional or mandatory. It may also
1314 operations, a move-only class should explicitly declare the move operations,
1315 and a non-copyable/movable class should explicitly delete the copy operations.
1357 <a href="#Structs_vs._Classes">struct</a> or an interface-only base class,
1361 naturally won't be either. An interface-only base class that leaves these
1396 appropriate keyword for the data-type you're
1451 <p> When a sub-class
1460 <p>Implementation inheritance reduces code size by re-using
1462 Because inheritance is a compile-time declaration, you
1472 implementing a sub-class is spread between the base and
1473 the sub-class, it can be more difficult to understand an
1474 implementation. The sub-class cannot override functions
1475 that are not virtual, so the sub-class cannot change
1494 inheritance to the "is-a" case: <code>Bar</code>
1522 <p>Overload operators judiciously. Do not use user-defined literals.</p>
1527 overloaded versions of the built-in operators</a> using the
1529 is a user-defined type. The <code>operator</code> keyword also
1531 <code>operator""</code>, and to define type-conversion functions
1536 intuitive by enabling user-defined types to behave the same
1537 as built-in types. Overloaded operators are the idiomatic names
1540 those conventions can make user-defined types more readable
1544 <p>User-defined literals are a very concise notation for
1545 creating objects of user-defined types.</p>
1561 thinking that expensive operations are cheap, built-in
1579 (comma) cannot match the evaluation-order semantics of the
1580 built-in operators.</li>
1587 run-time bugs.</li>
1589 <li>User-defined literals (UDLs) allow the creation of new
1595 <li>Because they can't be namespace-qualified, uses of UDLs also require
1596 use of either using-directives (which <a href="#Namespaces">we ban</a>) or
1597 using-declarations (which <a href="#Aliases">we ban in header files</a> except
1608 built-in operators. For example, use <code>|</code> as a
1609 bitwise- or logical-or, not as a shell-style pipe.</p>
1624 <p>Prefer to define non-modifying binary operators as
1625 non-member functions. If a binary operator is defined as a
1627 right-hand argument, but not the left-hand one. It will
1644 <code>operator""</code>, i.e. do not introduce user-defined
1690 performance-critical, and very short, methods may be
1704 performance. If output-only parameters are used,
1710 parameters will be pointers to non-<code>const</code>.</p>
1712 <p>When ordering function parameters, put all input-only
1715 because they are new; place new input-only parameters before
1718 <p>This is not a hard-and-fast rule. Parameters that are
1783 never allow non-<code>const</code> reference parameters
1831 identically-named function to take different arguments.
1854 that it is a well-designed overload set.</p>
1858 <p>Default arguments are allowed on non-virtual functions
1884 <p>Default parameters are re-evaluated at each call site,
1920 <pre>auto foo(int x) -> int;
1939 auto add(T t, U u) -> decltype(t + u);
1948 analogue in C++-like languages such as C and Java, so some readers may
1958 Use the new trailing-return-type form only in cases where it's
1966 <h2 id="Google-Specific_Magic">Google-Specific Magic</h2>
1997 <code>-></code> operators. Some smart pointer types
2030 ownership logic explicit, self-documenting, and
2070 run-time, which can be costly.</li>
2124 <a href="https://raw.githubusercontent.com/google/styleguide/gh-pages/cpplint/cpplint.py">
2141 or if you're writing low-overhead generic code that needs to support
2180 effective use of some standard-library types, such as
2198 references is counter-intuitive in signatures where the argument is expected
2252 nested functions, without the obscuring and error-prone
2264 <li>Some third-party C++ libraries use exceptions, and
2300 needed to make writing correct exception-safe code
2302 the entire call graph, exception-safe code must isolate
2329 exception-free code. Because most existing C++ code at
2335 exception-tolerant, the costs of using exceptions are
2337 conversion process would be slow and error-prone. We
2344 Because we'd like to use our open-source
2347 exceptions in Google open-source projects as well.
2369 <p>The <code>noexcept</code> operator performs a compile-time
2384 generate extra code for stack-unwinding, if it knows
2424 move-constructing objects), or on whether allocation can throw
2441 <h3 id="Run-Time_Type_Information__RTTI_">Run-Time Type
2454 require modification or redesign of the class hierarchy
2456 or undesirable, particularly in widely-used or mature
2478 <p>Querying the type of an object at run-time frequently
2481 of your class hierarchy is flawed.</p>
2484 It can lead to type-based decision trees or switch
2503 in some processing code, consider a double-dispatch
2506 determine the type of class using the built-in type
2525 } else if (typeid(*data) == typeid(D3)) {
2530 subclasses are added to the class hierarchy. Moreover,
2534 <p>Do not hand-implement an RTTI-like workaround. The
2541 <p>Use C++-style casts
2564 <p>The C++-style cast syntax is verbose and cumbersome.</p>
2567 <p>Do not use C-style casts. Instead, use these C++-style casts when
2578 <li>Use <code>static_cast</code> as the equivalent of a C-style cast
2580 explicitly up-cast a pointer from a class to its superclass, or when
2603 <p>See the <a href="#Run-Time_Type_Information__RTTI_">
2611 representing values, and write only the user-visible value, not any
2625 <code>std::string</code>, to say nothing of user-defined types,
2631 <p>Streams provide first-class support for console I/O
2645 built-in state, it can add new state variables and behaviors
2674 This is typically the case when the I/O is ad-hoc, local,
2675 human-readable, and targeted at other developers rather than
2676 end-users. Be consistent with the code around you, and with the
2706 <code><<</code> writes out a human-readable string
2722 decremented (<code>--i</code> or <code>i--</code>) and
2731 efficient. This is because post-increment (or decrement)
2734 iterator or other non-scalar type, copying <code>i</code>
2737 always pre-increment?</p>
2740 <p>The tradition developed, in C, of using post-increment
2742 <code>for</code> loops. Some find post-increment easier
2748 (non-object) values there is no reason to prefer one form
2750 types, use pre-increment.</p>
2774 are safe to use without locks in multi-threaded
2788 non-local variables) wherever it is meaningful and accurate. This
2789 provides consistent, mostly compiler-verified documentation
2792 is critical to writing thread-safe code, and is useful in
2798 should be a reference-to-const (<code>const T&</code>) or
2799 pointer-to-const (<code>const T*</code>), respectively.</li>
2811 that state, e.g. by returning a non-const reference, but that's
2820 be clearly documented as "thread-unsafe".</p>
2830 doesn't apply in codebases with few deeply-nested pointer
2858 constants with floating-point expressions rather than
2859 just literals; definition of constants of user-defined
2881 <p>Of the built-in C++ integer types, the only one used
2885 a precise-width integer type from
2889 (2GiB), use a 64-bit type such as
2929 assume that it has more than 32 bits. If you need a 64-bit
2965 unsigned integers to represent the size of containers - many members
2979 type merely to assert that a variable is non-negative.</p>
2981 <h3 id="64-bit_Portability">64-bit Portability</h3>
2983 <p>Code should be 64-bit and 32-bit friendly. Bear in mind
2997 …<a href="https://github.com/abseil/abseil-cpp/blob/master/absl/strings/str_cat.h"><code>StrCat</co…
3002 …<a href="https://github.com/abseil/abseil-cpp/blob/master/absl/strings/substitute.h"><code>Substit…
3014 typedefs to <code>printf</code>-based APIs. Note that it is acceptable
3023 you want a pointer-sized integer.</li>
3029 member will by default end up being 8-byte aligned on a
3030 64-bit system. If you have such structures being shared
3031 on disk between 32-bit and 64-bit code, you will need
3041 <p>Use <a href="#Casting">braced-initialization</a> as needed to create
3042 64-bit constants. For example:</p>
3057 Name macros with a project-specific prefix. Do not use
3086 performance-critical code, use an inline function.
3098 lower-level libraries. And some of their special features
3101 macro, consider carefully whether there's a non-macro way
3142 provides type-safety.</p>
3148 numeric (integer or floating-point) values.</p>
3231 also uses <code>auto</code> in the return-type position, but that doesn't
3235 <dt><a href="https://isocpp.org/wiki/faq/cpp14-language#generic-lambdas">Generic lambdas</a></dt>
3243 …<dt><a href="https://isocpp.org/wiki/faq/cpp14-language#lambda-captures">Lambda init captures</a><…
3261 iter->second = value;
3356 WidgetWithBellsAndWhistles& widget = *it->second;
3388 or the lambda is passed to an interface so well-known that it's
3408 pairs or tuples</a> unless a pre-existing API like <code>insert</code>
3441 array(T, U...) -> std::array<T, 1 + sizeof...(U)>;
3521 be used for capturing move-only variables by value, or for other situations
3557 <li>Variable capture in lambdas can be a source of dangling-pointer
3561 dangling-pointer bugs. Capturing a pointer by value doesn't cause a deep
3593 executor->Schedule([&] { Frobnicate(foo); })
3606 executor->Schedule([&foo] { Frobnicate(foo); })
3609 // BETTER - The compile will fail if `Frobnicate` is a member
3640 Turing complete and can be used to perform arbitrary compile-time
3672 <p>Template metaprogramming sometimes allows cleaner and easier-to-use
3682 non-C++ programmer or someone casually browsing the code base will be
3693 possible, so that user-facing headers are readable, and you should
3711 peer-reviewed, free, open-source C++ libraries.</p>
3714 <p>Boost code is generally very high-quality, is widely
3778 Multi-index</a> from <code>boost/multi_index</code></li>
3818 <p><code>std::hash</code> is defined for all integral, floating-point,
3838 because low-quality hash functions can be security vulnerabilities,
3840 <a href="https://emboss.github.io/blog/2012/12/14/breaking-murmur-hash-flooding-dos-reloaded/">
3846 on data members. High-quality hash algorithms maintain large
3896 <li>Compile-time rational numbers
3898 it's tied to a more template-heavy interface
3923 <code>foo = ({ int x; Bar(&x); x })</code>, variable-length arrays and
3942 are often not well-specified, and there may be subtle behavior differences
3952 are provided by a designated project-wide
3972 or in an explicitly-marked internal namespace. Aliases in such areas or in .cc files are
4046 declaration of that entity. The pattern-matching engine in our
4071 <code>n</code> may be a fine name within a 5-line function,
4085 std::string fqdn = ...; // Well-known abbreviation for Fully Qualified Domain Name
4110 <p>Note that certain universally-known abbreviations are OK, such as
4123 <a href="#Type_Names">type names</a>, and non-type template
4130 underscores (<code>_</code>) or dashes (<code>-</code>).
4140 <li><code>my-useful-class.cc</code></li>
4148 <a href="#Self_contained_Headers">self-contained headers</a>).</p>
4198 <pre>std::string table_name; // OK - lowercase with underscore.
4201 <pre class="badcode">std::string tableName; // Bad - mixed case.
4206 <p>Data members of classes, both static and non-static, are
4213 std::string table_name_; // OK - underscore at end.
4220 <p>Data members of structs, both static and non-static,
4266 <p>(The same naming rule applies to class- and namespace-scope
4278 Namespace names are all lower-case. Top-level namespace names are
4281 between nested namespaces and well-known top-level namespaces.
4283 <p>The name of a top-level namespace should usually be the
4297 <p>Avoid nested namespaces that match well-known top-level
4303 over collision-prone names like <code>websearch::util</code>.</p>
4343 macros. Hence, the change to prefer constant-style naming
4344 was put in place. New code should prefer constant-style
4346 old code to use constant-style names, unless the old
4347 names are actually causing a compile-time problem.</p>
4385 <dd>STL-like entity; follows STL naming conventions</dd>
4395 self-documenting. Giving sensible names to types and variables is much better than using obscure
4444 <p>If a <code>.h</code> declares multiple abstractions, the file-level comment
4446 related. A 1 or 2 sentence file-level comment may be sufficient. The detailed
4455 <p>Every non-obvious class declaration should have an accompanying
4460 // GargantuanTableIterator* iter = table->NewIterator();
4461 // for (iter->Seek("foo"); !iter->done(); iter->Next()) {
4462 // process(iter->key(), iter->value());
4488 non-obvious); comments at the definition of a function describe
4524 <li>If the function is re-entrant. What are its
4538 // Iterator* iter = table->NewIterator();
4539 // iter->Seek("");
4601 of sentinel values, such as nullptr or -1, when they are not
4605 // Used to bounds-check table accesses. -1 means
4623 non-obvious, interesting, or important parts of your code.</p>
4632 for (int i = 0; i < result->size(); ++i) {
4639 <h4>Line-end Comments</h4>
4641 <p>Also, lines that are non-obvious should get a comment
4642 at the end of the line. These end-of-line comments should
4646 mmap_budget = max<int64>(0, mmap_budget - index_->length());
4669 values self-describing.</li>
4712 <pre class="badcode">// Find the element in the vector. <-- Bad: obvious!
4728 Self-describing code doesn't need a comment. The comment from
4739 easier to read well-written comments than badly written
4759 a short-term solution, or good-enough but not perfect.</p>
4764 name, e-mail address, bug ID, or other
4808 <a href="https://raw.githubusercontent.com/google/styleguide/gh-pages/google-c-style.el">
4830 side-by-side, and thus don't have room to widen their
4838 code more readable. The 80-column limit is an hidebound
4849 readability, ease of cut and paste or auto-linking -- e.g. if a line
4852 <li>a raw-string literal with content that exceeds 80 characters. Except for
4859 <li>a using-declaration</li>
4862 <h3 id="Non-ASCII_Characters">Non-ASCII Characters</h3>
4864 <p>Non-ASCII characters should be rare, and must use UTF-8
4867 <p>You shouldn't hard-code user-facing text in source,
4868 even English, so use of non-ASCII characters should be
4872 appropriate to hard-code the non-ASCII string(s) used in
4875 contain non-ASCII strings. In such cases, you should use
4876 UTF-8, since that is an encoding
4883 <code>u8"\uFEFF"</code>, is the Unicode zero-width
4884 no-break space character, which would be invisible if
4885 included in the source as straight UTF-8.</p>
4889 <code>\uXXXX</code> escape sequences is encoded as UTF-8.
4890 Do not use it for strings containing non-ASCII characters
4891 encoded as UTF-8, because that will produce incorrect
4893 as UTF-8. </p>
4897 non-UTF-8 text. For similar reasons you also shouldn't
5010 <pre class="badcode">// Bad - if someone wants to implement later, it's not clear what the
5024 lists like other comma-separated lists.</p>
5026 <p>For by-reference captures, do not leave a space between the
5029 auto x_plus_n = [&x](int n) -> int { return x + n; }
5040 <h3 id="Floating_Literals">Floating-point Literals</h3>
5042 <p>Floating-point literals should always have a radix point, with digits on both
5044 floating-point literals take this familiar form, as this helps ensure that they
5047 hexadecimal digit. It is fine to initialize a floating-point variable with an
5053 long double ld = -.5L;
5059 long double ld = -0.5L;
5144 is no name, assume a zero-length name.</p>
5153 {"assume a zero-length name before {"},
5157 {"assume a zero-length name before {"},
5201 <pre>if ( condition ) { // spaces inside parentheses - rare
5213 <pre class="badcode">if(condition) { // Bad - space missing after IF.
5214 if (condition){ // Bad - space missing before {.
5218 <pre>if (condition) { // Good - proper space after IF and before {.
5233 <pre class="badcode">// Not allowed - IF statement on one line when there is an ELSE clause
5239 single-line statements, but they are allowed if you like
5256 <code>if</code>-<code>else</code> statement uses curly
5259 <pre class="badcode">// Not allowed - curly on IF but not ELSE
5265 // Not allowed - curly on ELSE but not IF
5285 non-trivial fall-through between cases.
5286 Braces are optional for single-statement loops.
5319 <p>Fall-through from one case label to
5325 point of execution where a fall-through to the next case
5349 <p> Braces are optional for single-statement loops.</p>
5366 for (int i = 0; i < kSomeNumber; ++i) {} // Good - one newline is also OK.
5367 while (condition) continue; // Good - continue indicates no logic.
5370 <pre class="badcode">while (condition); // Bad - looks like part of do/while loop.
5378 <p>The following are examples of correctly-formatted
5384 x = r->y;
5421 <pre class="badcode">int x, *y; // Disallowed - no & or * in multiple declaration
5422 char * c; // Bad - spaces on both sides of *
5423 const std::string & str; // Bad - spaces on both sides of &
5494 A nonempty <i>braced-init-list</i> prefers the
5498 non-<code>std::initializer_list</code> constructor, use parentheses
5509 <pre>int pi(3.14); // OK -- pi == 3.
5522 <pre>// Good - directives at beginning of line
5524 #if DISASTER_PENDING // Correct -- Starts at beginning of line
5526 # if NOTIFY // OK but not required -- Spaces after #
5534 <pre class="badcode">// Bad - indented directives
5578 the subclass name, subject to the 80-column limit.</li>
5678 // Spaces inside braces for braced-init-list are optional. If you use them,
5698 clean-up
5699 operation (preferably when no-one
5720 // Range-based for loops always have a space before and after the colon.
5743 x = -5;
5783 <li>Blank lines inside a chain of if-else blocks may
5802 <h3 id="Existing_Non-conformant_Code">Existing Non-conformant Code</h3>