From 3919c347aa79e6529e738b1270cc24767b830a51 Mon Sep 17 00:00:00 2001 From: Daniel Cheng Date: Fri, 25 Sep 2020 00:29:52 -0700 Subject: [PATCH] Update C++ styleguide - add section for inclusive language. - move include-what-you-use to a new section. - clarify usage of absl::optional for by-value vs by-reference params. - document usage of `` as a code-indexing hint - note that enclosing identifiers in `` can help code indexers. --- cppguide.html | 203 +++++++++++++++++++++++++++----------------------- 1 file changed, 111 insertions(+), 92 deletions(-) diff --git a/cppguide.html b/cppguide.html index c6dce95..6c52c11 100644 --- a/cppguide.html +++ b/cppguide.html @@ -247,14 +247,37 @@ guard:

+

Include What You Use

+ +

If a source or header file refers to a symbol defined elsewhere, +the file should directly include a header file which properly intends +to provide a declaration or definition of that symbol. It should not +include header files for any other reason. +

+ +

Do not rely on transitive inclusions. This allows people to remove +no-longer-needed #include statements from their headers without +breaking clients. This also applies to related headers +- foo.cc should include bar.h if it uses a +symbol from it even if foo.h +includes bar.h.

+

Forward Declarations

Avoid using forward declarations where possible. -Instead, #include the headers you need.

+ Instead, include the headers you need. +

+

-

A "forward declaration" is a declaration of a class, -function, or template without an associated definition.

+

A "forward declaration" is a declaration of an entity + without an associated definition.

+
// In a C++ source file:
+class B;
+void FuncInB();
+extern int variable_in_b;
+ABSL_DECLARE_FLAG(flag_in_b);
+

- - -

Please see Names and Order -of Includes for rules about when to #include a header.

+Try to avoid forward declarations of entities +defined in another project.

Inline Functions

@@ -453,14 +469,6 @@ Either style is acceptable, but prefer consistency with existing code.

alphabetically. Note that older code might not conform to this rule and should be fixed when convenient.

-

You should include all the headers that define the symbols you rely -upon, except in the unusual case of forward -declaration. If you rely on symbols from bar.h, -don't count on the fact that you included foo.h which -(currently) includes bar.h: include bar.h -yourself, unless foo.h explicitly demonstrates its intent -to provide you the symbols of bar.h.

-

For example, the includes in google-awesome-project/src/foo/internal/fooserver.cc @@ -563,7 +571,7 @@ namespaces, this can add a lot of clutter.

-

Template metaprogramming

+

Template Metaprogramming

Avoid complicated template programming.

@@ -3639,7 +3649,7 @@ computation in the type domain.

Template metaprogramming allows extremely flexible interfaces that are type safe and high performance. Facilities like -Google Test, +Google Test, std::tuple, std::function, and Boost.Spirit would be impossible without it.

@@ -3795,8 +3805,6 @@ features to the list, so this list may be expanded in the future.

- -

std::hash

Do not define specializations of std::hash.

@@ -3870,7 +3878,7 @@ using a new customization mechanism that doesn't have the drawbacks of -

Other C++ Features

+

Other C++ Features

As with Boost, some modern C++ extensions encourage coding practices that hamper @@ -4029,6 +4037,21 @@ typedef unordered_set<DataPoint, hash<DataPoint>, DataPointComparator&g using ::foo::Bar; +

Inclusive Language

+ +

In all code, including naming and comments, use inclusive language +and avoid terms that other programmers might find disrespectful or offensive +(such as "master" and "slave", "blacklist" and "whitelist", or "redline"), +even if the terms also have an ostensibly neutral meaning. +Similarly, use gender-neutral language unless you're referring +to a specific person (and using their preferred pronouns). For example, +use "they"/"them"/"their" for people of unspecified gender +(even +when singular), and "it"/"its" for software, computers, and other +things that aren't people.

+ + +

Naming

The most important consistency rules are those that govern @@ -4270,8 +4293,8 @@ set_count(int count).

Namespace Names

-Namespace names are all lower-case. Top-level namespace names are -based on the project name +Namespace names are all lower-case, with words separated by underscores. +Top-level namespace names are based on the project name . Avoid collisions between nested namespaces and well-known top-level namespaces. @@ -4446,11 +4469,10 @@ be used.

// Iterates over the contents of a GargantuanTable.
 // Example:
-//    GargantuanTableIterator* iter = table->NewIterator();
+//    std::unique_ptr<GargantuanTableIterator> iter = table->NewIterator();
 //    for (iter->Seek("foo"); !iter->done(); iter->Next()) {
 //      process(iter->key(), iter->value());
 //    }
-//    delete iter;
 class GargantuanTableIterator {
   ...
 };
@@ -4494,7 +4516,9 @@ left to comments in the function definition.

 declaration:

 
 
 
-
When declaring a pointer variable or argument, you may
-place the asterisk adjacent to either the type or to the
+
When declaring a pointer or reference variable or argument, you may
+place the asterisk/ampersand adjacent to either the type or the
 variable name:

 
 
// These are fine, space preceding.
@@ -5385,6 +5406,7 @@ reference decorations. Such declarations are easily misread.
 int x, y;
 

 
int x, *y;  // Disallowed - no & or * in multiple declaration
+int* x, *y;  // Disallowed - no & or * in multiple declaration; inconsistent spacing
 char * c;  // Bad - spaces on both sides of *
 const std::string & str;  // Bad - spaces on both sides of &
 

@@ -5440,9 +5462,6 @@ return(result);                // return is not a function!
 
 
Variable and Array Initialization

 
-
Your choice of =, (), or
-{}.

-
 
You may choose between =,
 (), and {}; the following are
 all correct: