mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
Merge pull request #630 from zetafunction/gh-pages
Update C++ style guide.
This commit is contained in:
commit
635fe96f8e
|
@ -84,14 +84,20 @@ site). </dd>
|
||||||
|
|
||||||
<dt>Be consistent with existing code</dt>
|
<dt>Be consistent with existing code</dt>
|
||||||
<dd>Using one style consistently through our codebase lets us focus on
|
<dd>Using one style consistently through our codebase lets us focus on
|
||||||
other (more important) issues. Consistency also allows for
|
other (more important) issues. Consistency also allows for automation:
|
||||||
automation: tools that format your code or adjust
|
tools that format your code or adjust your <code>#include</code>s only
|
||||||
your <code>#include</code>s only work properly when your code is
|
work properly when your code is consistent with the expectations of
|
||||||
consistent with the expectations of the tooling. In many cases, rules
|
the tooling. In many cases, rules that are attributed to "Be
|
||||||
that are attributed to "Be Consistent" boil down to "Just pick one and
|
Consistent" boil down to "Just pick one and stop worrying about it";
|
||||||
stop worrying about it"; the potential value of allowing flexibility
|
the potential value of allowing flexibility on these points is
|
||||||
on these points is outweighed by the cost of having people argue over
|
outweighed by the cost of having people argue over them. However,
|
||||||
them. </dd>
|
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.</dd>
|
||||||
|
|
||||||
<dt>Be consistent with the broader C++ community when appropriate</dt>
|
<dt>Be consistent with the broader C++ community when appropriate</dt>
|
||||||
<dd>Consistency with the way other organizations use C++ has value for
|
<dd>Consistency with the way other organizations use C++ has value for
|
||||||
|
@ -1678,7 +1684,7 @@ be <code>protected</code> when using
|
||||||
|
|
||||||
|
|
||||||
<a href="https://github.com/google/googletest">Google
|
<a href="https://github.com/google/googletest">Google
|
||||||
Test</a>).
|
Test</a>.
|
||||||
If a test fixture class is defined outside of the .cc file it is used in, for example in a .h file,
|
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 <code>private</code>.</p>
|
make data members <code>private</code>.</p>
|
||||||
|
|
||||||
|
@ -1695,7 +1701,7 @@ sections that would be empty.</p>
|
||||||
<p>Within each section, prefer grouping similar
|
<p>Within each section, prefer grouping similar
|
||||||
kinds of declarations together, and prefer the
|
kinds of declarations together, and prefer the
|
||||||
following order: types (including <code>typedef</code>,
|
following order: types (including <code>typedef</code>,
|
||||||
<code>using</code>, and nested structs and classes),
|
<code>using</code>, <code>enum</code>, and nested structs and classes),
|
||||||
constants, factory functions, constructors and assignment
|
constants, factory functions, constructors and assignment
|
||||||
operators, destructor, all other methods, data members.</p>
|
operators, destructor, all other methods, data members.</p>
|
||||||
|
|
||||||
|
@ -1730,6 +1736,8 @@ inputs, and use a <code>const</code> pointer when the non-optional form would
|
||||||
have used a reference. Use non-<code>const</code> pointers to represent
|
have used a reference. Use non-<code>const</code> pointers to represent
|
||||||
optional outputs and optional input/output parameters.</p>
|
optional outputs and optional input/output parameters.</p>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
Avoid defining functions that require a <code>const</code> reference parameter
|
Avoid defining functions that require a <code>const</code> reference parameter
|
||||||
to outlive the call, because <code>const</code> reference parameters bind
|
to outlive the call, because <code>const</code> reference parameters bind
|
||||||
|
@ -2505,7 +2513,7 @@ workarounds disguise your true intent.</p>
|
||||||
<p>Use C++-style casts
|
<p>Use C++-style casts
|
||||||
like <code>static_cast<float>(double_value)</code>, or brace
|
like <code>static_cast<float>(double_value)</code>, or brace
|
||||||
initialization for conversion of arithmetic types like
|
initialization for conversion of arithmetic types like
|
||||||
<code>int64 y = int64{1} << 42</code>. Do not use
|
<code>int64_t y = int64_t{1} << 42</code>. Do not use
|
||||||
cast formats like <code>(int)x</code> unless the cast is to
|
cast formats like <code>(int)x</code> unless the cast is to
|
||||||
<code>void</code>. You may use cast formats like `T(x)` only when
|
<code>void</code>. You may use cast formats like `T(x)` only when
|
||||||
`T` is a class type.</p>
|
`T` is a class type.</p>
|
||||||
|
@ -2534,7 +2542,7 @@ casts when explicit type conversion is necessary.
|
||||||
|
|
||||||
<ul>
|
<ul>
|
||||||
<li>Use brace initialization to convert arithmetic types
|
<li>Use brace initialization to convert arithmetic types
|
||||||
(e.g., <code>int64{x}</code>). This is the safest approach because code
|
(e.g., <code>int64_t{x}</code>). This is the safest approach because code
|
||||||
will not compile if conversion can result in information loss. The
|
will not compile if conversion can result in information loss. The
|
||||||
syntax is also concise.</li>
|
syntax is also concise.</li>
|
||||||
|
|
||||||
|
@ -2563,7 +2571,7 @@ casts when explicit type conversion is necessary.
|
||||||
<li>Use <code>absl::bit_cast</code> to interpret the raw bits of a
|
<li>Use <code>absl::bit_cast</code> to interpret the raw bits of a
|
||||||
value using a different type of the same size (a type pun), such as
|
value using a different type of the same size (a type pun), such as
|
||||||
interpreting the bits of a <code>double</code> as
|
interpreting the bits of a <code>double</code> as
|
||||||
<code>int64</code>.</li>
|
<code>int64_t</code>.</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
<p>See the <a href="#Run-Time_Type_Information__RTTI_">
|
<p>See the <a href="#Run-Time_Type_Information__RTTI_">
|
||||||
|
@ -2839,13 +2847,11 @@ enable their use with <code>constexpr</code>. Do not use
|
||||||
<p>Of the built-in C++ integer types, the only one used
|
<p>Of the built-in C++ integer types, the only one used
|
||||||
is
|
is
|
||||||
<code>int</code>. If a program needs a variable of a
|
<code>int</code>. If a program needs a variable of a
|
||||||
different size, use
|
different size, use a precise-width integer type from
|
||||||
a precise-width integer type from
|
|
||||||
<code><stdint.h></code>, such as
|
<code><stdint.h></code>, such as
|
||||||
<code>int16_t</code>. If your variable represents a
|
<code>int16_t</code>. If your variable represents a
|
||||||
value that could ever be greater than or equal to 2^31
|
value that could ever be greater than or equal to 2^31
|
||||||
(2GiB), use a 64-bit type such as
|
(2GiB), use a 64-bit type such as <code>int64_t</code>.
|
||||||
<code>int64_t</code>.
|
|
||||||
Keep in mind that even if your value won't ever be too large
|
Keep in mind that even if your value won't ever be too large
|
||||||
for an <code>int</code>, it may be used in intermediate
|
for an <code>int</code>, it may be used in intermediate
|
||||||
calculations which may require a larger type. When in doubt,
|
calculations which may require a larger type. When in doubt,
|
||||||
|
@ -2867,17 +2873,6 @@ compiler and architecture.</p>
|
||||||
|
|
||||||
<p class="decision"></p>
|
<p class="decision"></p>
|
||||||
|
|
||||||
<p>
|
|
||||||
<code><cstdint></code> defines types
|
|
||||||
like <code>int16_t</code>, <code>uint32_t</code>,
|
|
||||||
<code>int64_t</code>, etc. You should always use
|
|
||||||
those in preference to <code>short</code>, <code>unsigned
|
|
||||||
long long</code> and the like, when you need a guarantee
|
|
||||||
on the size of an integer. Of the C integer types, only
|
|
||||||
<code>int</code> should be used. When appropriate, you
|
|
||||||
are welcome to use standard types like
|
|
||||||
<code>size_t</code> and <code>ptrdiff_t</code>.</p>
|
|
||||||
|
|
||||||
<p>We use <code>int</code> very often, for integers we
|
<p>We use <code>int</code> very often, for integers we
|
||||||
know are not going to be too big, e.g., loop counters.
|
know are not going to be too big, e.g., loop counters.
|
||||||
Use plain old <code>int</code> for such things. You
|
Use plain old <code>int</code> for such things. You
|
||||||
|
@ -2885,18 +2880,14 @@ should assume that an <code>int</code> is
|
||||||
|
|
||||||
at least 32 bits, but don't
|
at least 32 bits, but don't
|
||||||
assume that it has more than 32 bits. If you need a 64-bit
|
assume that it has more than 32 bits. If you need a 64-bit
|
||||||
integer type, use
|
integer type, use <code>int64_t</code> or <code>uint64_t</code>.
|
||||||
<code>int64_t</code>
|
|
||||||
or
|
|
||||||
<code>uint64_t</code>.</p>
|
|
||||||
|
|
||||||
<p>For integers we know can be "big",
|
</p><p>For integers we know can be "big",
|
||||||
use
|
use
|
||||||
<code>int64_t</code>.
|
<code>int64_t</code>.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p>You should not use the unsigned integer types such as
|
<p>You should not use the unsigned integer types such as
|
||||||
|
|
||||||
<code>uint32_t</code>, unless there is a valid
|
<code>uint32_t</code>, unless there is a valid
|
||||||
reason such as representing a bit pattern rather than a
|
reason such as representing a bit pattern rather than a
|
||||||
number, or you need defined overflow modulo 2^N. In
|
number, or you need defined overflow modulo 2^N. In
|
||||||
|
@ -2967,7 +2958,6 @@ problems of printing, comparisons, and structure alignment.</p>
|
||||||
specify a conversion for the standard bitwidth typedefs (e.g.,
|
specify a conversion for the standard bitwidth typedefs (e.g.,
|
||||||
<code>int64_t</code>, <code>uint64_t</code>, <code>int32_t</code>,
|
<code>int64_t</code>, <code>uint64_t</code>, <code>int32_t</code>,
|
||||||
<code>uint32_t</code>, etc).
|
<code>uint32_t</code>, etc).
|
||||||
|
|
||||||
Where possible, avoid passing arguments of types specified by bitwidth
|
Where possible, avoid passing arguments of types specified by bitwidth
|
||||||
typedefs to <code>printf</code>-based APIs. Note that it is acceptable
|
typedefs to <code>printf</code>-based APIs. Note that it is acceptable
|
||||||
to use typedefs for which printf has dedicated length modifiers, such as
|
to use typedefs for which printf has dedicated length modifiers, such as
|
||||||
|
@ -2982,8 +2972,7 @@ problems of printing, comparisons, and structure alignment.</p>
|
||||||
|
|
||||||
<li>You may need to be careful with structure
|
<li>You may need to be careful with structure
|
||||||
alignments, particularly for structures being stored on
|
alignments, particularly for structures being stored on
|
||||||
disk. Any class/structure with a
|
disk. Any class/structure with a <code>int64_t</code>/<code>uint64_t</code>
|
||||||
<code>int64_t</code>/<code>uint64_t</code>
|
|
||||||
member will by default end up being 8-byte aligned on a
|
member will by default end up being 8-byte aligned on a
|
||||||
64-bit system. If you have such structures being shared
|
64-bit system. If you have such structures being shared
|
||||||
on disk between 32-bit and 64-bit code, you will need
|
on disk between 32-bit and 64-bit code, you will need
|
||||||
|
@ -2998,13 +2987,9 @@ problems of printing, comparisons, and structure alignment.</p>
|
||||||
<li>
|
<li>
|
||||||
<p>Use <a href="#Casting">braced-initialization</a> as needed to create
|
<p>Use <a href="#Casting">braced-initialization</a> as needed to create
|
||||||
64-bit constants. For example:</p>
|
64-bit constants. For example:</p>
|
||||||
|
|
||||||
|
|
||||||
<div>
|
|
||||||
<pre>int64_t my_value{0x123456789};
|
<pre>int64_t my_value{0x123456789};
|
||||||
uint64_t my_mask{3ULL << 48};
|
uint64_t my_mask{3ULL << 48};
|
||||||
</pre>
|
</pre>
|
||||||
</div>
|
|
||||||
</li>
|
</li>
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
@ -3648,7 +3633,7 @@ computation in the type domain.</p>
|
||||||
<p>Template metaprogramming allows extremely flexible interfaces that
|
<p>Template metaprogramming allows extremely flexible interfaces that
|
||||||
are type safe and high performance. Facilities like
|
are type safe and high performance. Facilities like
|
||||||
|
|
||||||
<a href="https://github.com/google/googletest">Google Test</a>,
|
<a href="https://github.com/google/googletest">GoogleTest</a>,
|
||||||
<code>std::tuple</code>, <code>std::function</code>, and
|
<code>std::tuple</code>, <code>std::function</code>, and
|
||||||
Boost.Spirit would be impossible without it.</p>
|
Boost.Spirit would be impossible without it.</p>
|
||||||
|
|
||||||
|
@ -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:</p>
|
be separated from the code by 2 spaces. Example:</p>
|
||||||
|
|
||||||
<pre>// If we have enough memory, mmap the data portion too.
|
<pre>// 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))
|
if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
|
||||||
return; // Error already logged.
|
return; // Error already logged.
|
||||||
</pre>
|
</pre>
|
||||||
|
|
Loading…
Reference in New Issue
Block a user