StarMirror/styleguide
1
0
Fork 0
mirror of https://github.com/google/styleguide.git synced 2024-03-22 13:11:43 +08:00
Code Issues Projects Releases Wiki Activity

Update C++ style guide to 3.170:

Browse Source 
- Allow overloading a function judiciously.
 - _unittest and _regtest are deprecated.
 - Document C++0x policy.
 - Allow namespace aliases in .h files when inside namespaces.
 - Give examples for and against parentheses with return.
 - Update set of allowed Boost headers.
 - Add a caveat to the forward-declaration section, mentioning impicit
   constructors.
This commit is contained in:
mmentovai 2010-08-05 00:39:32 +00:00
parent 8411f0c651
commit b6870cb5db
1 changed files with 150 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

208
cppguide.xml
View File

@ -4,7 +4,7 @@
<p align="right"> <p align="right">
Revision 3.161 Revision 3.170
</p> </p>
@ -148,7 +148,7 @@ Tashana Landray
<STYLEPOINT title="Header File Dependencies"> <STYLEPOINT title="Header File Dependencies">
<SUMMARY> <SUMMARY>
Don't use an <code>#include</code> when a forward declaration Don't use an <code>#include</code> when a forward declaration
would suffice. would suffice.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
@ -178,7 +178,13 @@ Tashana Landray
<code>Foo&amp;</code>. <code>Foo&amp;</code>.
</li> </li>
<li> We can declare (but not define) functions with arguments, <li> We can declare (but not define) functions with arguments,
and/or return values, of type <code>Foo</code>. and/or return values, of type <code>Foo</code>. (One
exception is if an argument <code>Foo</code>
or <code>const Foo&amp;</code> has a
non-<code>explicit</code>, one-argument constructor,
in which case we need the full definition to support
automatic type conversion.)
</li> </li>
<li> We can declare static data members of type <li> We can declare static data members of type
<code>Foo</code>. This is because static data members <code>Foo</code>. This is because static data members
@ -386,7 +392,7 @@ Tashana Landray
<p> <p>
<code><var>dir/foo</var>.cc</code> and <code><var>dir/foo</var>.cc</code> and
<code><var>dir2/foo2</var>.h</code> are often in the same <code><var>dir2/foo2</var>.h</code> are often in the same
directory (e.g. <code>base/basictypes_unittest.cc</code> and directory (e.g. <code>base/basictypes_test.cc</code> and
<code>base/basictypes.h</code>), but can be in different <code>base/basictypes.h</code>), but can be in different
directories too. directories too.
</p> </p>
@ -581,13 +587,35 @@ Tashana Landray
</li> </li>
<li> Namespace aliases are allowed anywhere in a <li> Namespace aliases are allowed anywhere in a
<code>.cc</code> file, and in functions and methods in <code>.cc</code> file, anywhere inside the named
<code>.h</code> files. namespace that wraps an entire <code>.h</code> file,
and in functions and methods.
<CODE_SNIPPET> <CODE_SNIPPET>
// OK in .cc files. // Shorten access to some commonly used names in .cc files.
// Must be in a function or method in .h files.
namespace fbz = ::foo::bar::baz; namespace fbz = ::foo::bar::baz;
// Shorten access to some commonly used names (in a .h file).
namespace librarian {
// The following alias is avaliable to all files including
// this header (in namespace librarian):
// alias names should therefore be chosen consistently
// within a project.
namespace pd_s = ::pipeline_diagnostics::sidetable;
inline void my_inline_function() {
// namespace alias local to a function (or method).
namespace fbz = ::foo::bar::baz;
...
}
} // namespace librarian
</CODE_SNIPPET> </CODE_SNIPPET>
<p>
Note that an alias in a .h file is visible to everyone
#including that file, so public headers (those available
outside a project) and headers transitively #included by them,
should avoid defining aliases, as part of the general
goal of keeping public APIs as small as possible.
</p>
</li> </li>
</ul> </ul>
</SUBSECTION> </SUBSECTION>
@ -1474,7 +1502,7 @@ Tashana Landray
<BODY> <BODY>
<p> <p>
<code>cpplint.py</code> <code>cpplint.py</code>
is a tool that reads a source file and is a tool that reads a source file and
identifies many style errors. It is not perfect, and has both false identifies many style errors. It is not perfect, and has both false
positives and false negatives, but it is still a valuable tool. False positives and false negatives, but it is still a valuable tool. False
positives can be ignored by putting <code>// NOLINT</code> at positives can be ignored by putting <code>// NOLINT</code> at
@ -1547,10 +1575,10 @@ Tashana Landray
<STYLEPOINT title="Function Overloading"> <STYLEPOINT title="Function Overloading">
<SUMMARY> <SUMMARY>
Use overloaded functions (including constructors) only in cases Use overloaded functions (including constructors) only if a
where input can be specified in different types that contain the reader looking at a call site can get a good idea of what is
same information. Do not use function overloading to simulate happening without having to first figure out exactly which
<A HREF="#Default_Arguments">default function parameters</A>. overload is being called.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<DEFINITION> <DEFINITION>
@ -1574,20 +1602,18 @@ Tashana Landray
convenient for Visitors. convenient for Visitors.
</PROS> </PROS>
<CONS> <CONS>
One reason to minimize function overloading is that If a function is overloaded by the argument types alone, a
overloading can make it hard to tell which function is being reader may have to understand C++'s complex matching rules in
called at a particular call site. Another one is that most order to tell what's going on. Also many people are confused
people are confused by the semantics of inheritance if a by the semantics of inheritance if a derived class overrides
deriving class overrides only some of the variants of a only some of the variants of a function.
function. Moreover, reading client code of a library may
become unnecessarily hard because of all the reasons against
<A HREF="#Default_Arguments">default function parameters</A>.
</CONS> </CONS>
<DECISION> <DECISION>
If you want to overload a function, consider qualifying the If you want to overload a function, consider qualifying the
name with some information about the arguments, e.g., name with some information about the arguments, e.g.,
<code>AppendString()</code>, <code>AppendInt()</code> rather <code>AppendString()</code>, <code>AppendInt()</code> rather
than just <code>Append()</code>. than just <code>Append()</code>.
</DECISION> </DECISION>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -2517,40 +2543,97 @@ Tashana Landray
techniques, and an excessively "functional" style of programming. techniques, and an excessively "functional" style of programming.
</CONS> </CONS>
<DECISION> <DECISION>
In order to maintain a high level of readability for all contributors <div>
who might read and maintain code, we only allow an approved subset of
Boost features. Currently, the following libraries are permitted: In order to maintain a high level of readability for all contributors
<ul> who might read and maintain code, we only allow an approved subset of
<li> <a href="http://www.boost.org/libs/utility/call_traits.htm"> Boost features. Currently, the following libraries are permitted:
Call Traits</a> from <code>boost/call_traits.hpp</code> <ul>
</li> <li> <a href="http://www.boost.org/libs/utility/call_traits.htm">
<li> <a href="http://www.boost.org/libs/utility/compressed_pair.htm"> Call Traits</a> from <code>boost/call_traits.hpp</code>
Compressed Pair</a> from <code>boost/compressed_pair.hpp</code> </li>
</li> <li> <a href="http://www.boost.org/libs/utility/compressed_pair.htm">
<li> <a href="http://www.boost.org/libs/ptr_container/"> Compressed Pair</a> from <code>boost/compressed_pair.hpp</code>
Pointer Container</a> from <code>boost/ptr_container</code> except serialization </li>
</li> <li> <a href="http://www.boost.org/libs/ptr_container/">
<li> <a href="http://www.boost.org/libs/array/"> Pointer Container</a> from <code>boost/ptr_container</code> except
Array</a> from <code>boost/array.hpp</code> serialization and wrappers for containers not in the C++03
</li> standard (<code>ptr_circular_buffer.hpp</code> and
<li> <a href="http://www.boost.org/libs/graph/"> <code>ptr_unordered*</code>)
The Boost Graph Library (BGL)</a> from <code>boost/graph</code> except serialization </li>
</li> <li> <a href="http://www.boost.org/libs/array/">
<li> <a href="http://www.boost.org/libs/property_map/"> Array</a> from <code>boost/array.hpp</code>
Property Map</a> from <code>boost/property_map.hpp</code> </li>
</li> <li> <a href="http://www.boost.org/libs/graph/">
<li> The part of The Boost Graph Library (BGL)</a> from <code>boost/graph</code>,
<a href="http://www.boost.org/libs/iterator/"> except serialization (<code>adj_list_serialize.hpp</code>) and
Iterator</a> that deals with defining iterators: parallel/distributed algorithms and data structures
<code>boost/iterator/iterator_adaptor.hpp</code>, (<code>boost/graph/parallel/*</code> and
<code>boost/iterator/iterator_facade.hpp</code>, and <code>boost/graph/distributed/*</code>).
<code>boost/function_output_iterator.hpp</code></li> </li>
</ul> <li> <a href="http://www.boost.org/libs/property_map/">
We are actively considering adding other Boost features to the list, so Property Map</a> from <code>boost/property_map</code>, except
this rule may be relaxed in the future. parallel/distributed property maps
(<code>boost/property_map/parallel/*</code>).
</li>
<li> The part of
<a href="http://www.boost.org/libs/iterator/">
Iterator</a> that deals with defining iterators:
<code>boost/iterator/iterator_adaptor.hpp</code>,
<code>boost/iterator/iterator_facade.hpp</code>, and
<code>boost/function_output_iterator.hpp</code></li>
</ul>
We are actively considering adding other Boost features to the list, so
this rule may be relaxed in the future.
</div>
</DECISION>
</BODY>
</STYLEPOINT>
<STYLEPOINT title="C++0x">
<SUMMARY>
Use only approved libraries and language extensions from C++0x.
Currently, none are approved.
</SUMMARY>
<BODY>
<DEFINITION>
C++0x is the next ISO C++ standard, currently in
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3092.pdf">final
committee draft</a> form. It contains
<a href="http://en.wikipedia.org/wiki/C%2B%2B0x">significant
changes</a> both to the language and libraries.
</DEFINITION>
<PROS>
We expect that C++0x will become the next standard, and eventually will
be supported by most C++ compilers. It standardizes some common C++
extensions that we use already, allows shorthands for some operations,
and has some safety improvements.
</PROS>
<CONS>
<p>
The C++0x standard is substantialy more complex than its predecessor
(1,300 pages versus 800 pages), and is
unfamilar to many developers. The long-term effects of some
features on code readability and maintenance are unknown. We cannot
predict when its various features will be implemented uniformly by
tools that may be of interest (gcc, icc, clang, Eclipse, etc.).
</p>
<p>
As with <a href="#Boost">Boost</a>, some C++0x extensions encourage
coding practices that hamper readability&#8212;for example by removing
checked redundancy (such as type names) that may be helpful to readers,
or by encouraging template metaprogramming. Other extensions
duplicate functionality available through existing
mechanisms, which may lead to
confusion and conversion costs.
</p>
</CONS>
<DECISION>
Use only C++0x libraries and language features that have been approved
for use. Currently, no such features are approved.
Features will be approved individually as appropriate.
</DECISION> </DECISION>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -2665,6 +2748,7 @@ Tashana Landray
my_useful_class.cc<br/> my_useful_class.cc<br/>
my-useful-class.cc<br/> my-useful-class.cc<br/>
myusefulclass.cc<br/> myusefulclass.cc<br/>
myusefulclass_test.cc // _unittest and _regtest are deprecated.<br/>
</code> </code>
</p> </p>
<p> <p>
@ -2825,7 +2909,7 @@ Tashana Landray
Functions should start with a capital letter and have a Functions should start with a capital letter and have a
capital letter for each new word. No underscores. capital letter for each new word. No underscores.
</p> </p>
<p> <p>
If your function crashes upon an error, you should append OrDie to If your function crashes upon an error, you should append OrDie to
the function name. This only applies to functions which could be the function name. This only applies to functions which could be
used by production code and to errors that are reasonably used by production code and to errors that are reasonably
@ -3942,15 +4026,23 @@ Tashana Landray
<STYLEPOINT title="Return Values"> <STYLEPOINT title="Return Values">
<SUMMARY> <SUMMARY>
Do not surround the <code>return</code> expression with parentheses. Do not needlessly surround the <code>return</code> expression with
parentheses.
</SUMMARY> </SUMMARY>
<BODY> <BODY>
<p> <p>
Return values should not have parentheses: Use parentheses in <code>return expr;</code> only where you would use
them in <code>x = expr;</code>.
</p> </p>
<CODE_SNIPPET> <CODE_SNIPPET>
return x; // not return(x); return result; // No parentheses in the simple case.
return (some_long_condition &amp;&amp; // Parentheses ok to make a complex
another_condition); // expression more readable.
</CODE_SNIPPET> </CODE_SNIPPET>
<BAD_CODE_SNIPPET>
return (value); // You wouldn't write var = (value);
return(result); // return is not a function!
</BAD_CODE_SNIPPET>
</BODY> </BODY>
</STYLEPOINT> </STYLEPOINT>
@ -4422,7 +4514,7 @@ Tashana Landray
<HR/> <HR/>
<p align="right"> <p align="right">
Revision 3.161 Revision 3.170
</p> </p>