From 4e25657924db86f507b74ee64e9bf35ebead1ed4 Mon Sep 17 00:00:00 2001 From: Daniel Cheng Date: Fri, 26 Mar 2021 16:46:04 -0700 Subject: [PATCH] Update C++ style guide. Mostly minor wording updates (e.g. preferring int64_t to int64). The most significant change is clarifying the section on consistency to clarify that consistency, in and of itself, should not be used as the sole argument for blocking adoption of style changes. --- cppguide.html | 71 ++++++++++++++++++++------------------------------- 1 file changed, 28 insertions(+), 43 deletions(-) diff --git a/cppguide.html b/cppguide.html index 1997a10..c529395 100644 --- a/cppguide.html +++ b/cppguide.html @@ -84,14 +84,20 @@ site).
Be consistent with existing code
Using one style consistently through our codebase lets us focus on -other (more important) issues. Consistency also allows for -automation: tools that format your code or adjust -your #includes only work properly when your code is -consistent with the expectations of the tooling. In many cases, rules -that are attributed to "Be Consistent" boil down to "Just pick one and -stop worrying about it"; the potential value of allowing flexibility -on these points is outweighed by the cost of having people argue over -them.
+other (more important) issues. Consistency also allows for automation: +tools that format your code or adjust your #includes only +work properly when your code is consistent with the expectations of +the tooling. In many cases, rules that are attributed to "Be +Consistent" boil down to "Just pick one and stop worrying about it"; +the potential value of allowing flexibility on these points is +outweighed by the cost of having people argue over them. However, +there are limits to consistency; it is a good tie breaker when there +is no clear technical argument, nor a long-term direction. It applies +more heavily locally (per file, or for a tightly-related set of +interfaces). Consistency should not generally be used as a +justification to do things in an old style without considering the +benefits of the new style, or the tendency of the codebase to converge +on newer styles over time.
Be consistent with the broader C++ community when appropriate
Consistency with the way other organizations use C++ has value for @@ -1678,7 +1684,7 @@ be protected when using Google -Test). +Test. If a test fixture class is defined outside of the .cc file it is used in, for example in a .h file, make data members private.

@@ -1695,7 +1701,7 @@ sections that would be empty.

Within each section, prefer grouping similar kinds of declarations together, and prefer the following order: types (including typedef, -using, and nested structs and classes), +using, enum, and nested structs and classes), constants, factory functions, constructors and assignment operators, destructor, all other methods, data members.

@@ -1730,6 +1736,8 @@ inputs, and use a const pointer when the non-optional form would have used a reference. Use non-const pointers to represent optional outputs and optional input/output parameters.

+ +

Avoid defining functions that require a const reference parameter to outlive the call, because const reference parameters bind @@ -2505,7 +2513,7 @@ workarounds disguise your true intent.

Use C++-style casts like static_cast<float>(double_value), or brace initialization for conversion of arithmetic types like -int64 y = int64{1} << 42. Do not use +int64_t y = int64_t{1} << 42. Do not use cast formats like (int)x unless the cast is to void. You may use cast formats like `T(x)` only when `T` is a class type.

@@ -2534,7 +2542,7 @@ casts when explicit type conversion is necessary.

See the @@ -2839,13 +2847,11 @@ enable their use with constexpr. Do not use

Of the built-in C++ integer types, the only one used is int. If a program needs a variable of a -different size, use -a precise-width integer type from +different size, use a precise-width integer type from <stdint.h>, such as int16_t. If your variable represents a value that could ever be greater than or equal to 2^31 -(2GiB), use a 64-bit type such as -int64_t. +(2GiB), use a 64-bit type such as int64_t. Keep in mind that even if your value won't ever be too large for an int, it may be used in intermediate calculations which may require a larger type. When in doubt, @@ -2867,17 +2873,6 @@ compiler and architecture.

-

-<cstdint> defines types -like int16_t, uint32_t, -int64_t, etc. You should always use -those in preference to short, unsigned -long long and the like, when you need a guarantee -on the size of an integer. Of the C integer types, only -int should be used. When appropriate, you -are welcome to use standard types like -size_t and ptrdiff_t.

-

We use int very often, for integers we know are not going to be too big, e.g., loop counters. Use plain old int for such things. You @@ -2885,18 +2880,14 @@ should assume that an int is at least 32 bits, but don't assume that it has more than 32 bits. If you need a 64-bit -integer type, use -int64_t -or -uint64_t.

+integer type, use int64_t or uint64_t. -

For integers we know can be "big", +

For integers we know can be "big", use int64_t.

You should not use the unsigned integer types such as - uint32_t, unless there is a valid reason such as representing a bit pattern rather than a number, or you need defined overflow modulo 2^N. In @@ -2967,7 +2958,6 @@ problems of printing, comparisons, and structure alignment.

specify a conversion for the standard bitwidth typedefs (e.g., int64_t, uint64_t, int32_t, uint32_t, etc). - Where possible, avoid passing arguments of types specified by bitwidth typedefs to printf-based APIs. Note that it is acceptable to use typedefs for which printf has dedicated length modifiers, such as @@ -2982,8 +2972,7 @@ problems of printing, comparisons, and structure alignment.

  • You may need to be careful with structure alignments, particularly for structures being stored on - disk. Any class/structure with a - int64_t/uint64_t + disk. Any class/structure with a int64_t/uint64_t member will by default end up being 8-byte aligned on a 64-bit system. If you have such structures being shared on disk between 32-bit and 64-bit code, you will need @@ -2998,13 +2987,9 @@ problems of printing, comparisons, and structure alignment.

  • Use braced-initialization as needed to create 64-bit constants. For example:

    - - -
    int64_t my_value{0x123456789};
 uint64_t my_mask{3ULL << 48};
    -
    • @@ -3648,7 +3633,7 @@ computation in the type domain.

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

    @@ -4651,7 +4636,7 @@ at the end of the line. These end-of-line comments should be separated from the code by 2 spaces. Example:

    // If we have enough memory, mmap the data portion too.
-mmap_budget = max<int64>(0, mmap_budget - index_->length());
+mmap_budget = max<int64_t>(0, mmap_budget - index_->length());
 if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
   return;  // Error already logged.