Google C++ Style Guide
+ + +Background
+ +C++ is one of the main development languages used by +many of Google's open-source projects. As every C++ +programmer knows, the language has many powerful features, but +this power brings with it complexity, which in turn can make +code more bug-prone and harder to read and maintain.
+ +The goal of this guide is to manage this complexity by +describing in detail the dos and don'ts of writing C++ code. +These rules exist to +keep the code base manageable while still allowing +coders to use C++ language features productively.
+ +Style, also known as readability, is what we call +the conventions that govern our C++ code. The term Style is a +bit of a misnomer, since these conventions cover far more than +just source file formatting.
+ ++Most open-source projects developed by +Google conform to the requirements in this guide. +
+ + + + + +Note that this guide is not a C++ tutorial: we assume that +the reader is familiar with the language.
+ +Goals of the Style Guide
+Why do we have this document?
+ +There are a few core goals that we believe this guide should +serve. These are the fundamental whys that +underlie all of the individual rules. By bringing these ideas to +the fore, we hope to ground discussions and make it clearer to our +broader community why the rules are in place and why particular +decisions have been made. If you understand what goals each rule is +serving, it should be clearer to everyone when a rule may be waived +(some can be), and what sort of argument or alternative would be +necessary to change a rule in the guide.
+ +The goals of the style guide as we currently see them are as follows:
+-
+
- Style rules should pull their weight +
- The benefit of a style rule
+must be large enough to justify asking all of our engineers to
+remember it. The benefit is measured relative to the codebase we would
+get without the rule, so a rule against a very harmful practice may
+still have a small benefit if people are unlikely to do it
+anyway. This principle mostly explains the rules we don’t have, rather
+than the rules we do: for example,
gotocontravenes many +of the following principles, but is already vanishingly rare, so the Style +Guide doesn’t discuss it.
+
+ - Optimize for the reader, not the writer +
- Our codebase (and most individual components submitted to it) is
+expected to continue for quite some time. As a result, more time will
+be spent reading most of our code than writing it. We explicitly
+choose to optimize for the experience of our average software engineer
+reading, maintaining, and debugging code in our codebase rather than
+ease when writing said code. "Leave a trace for the reader" is a
+particularly common sub-point of this principle: When something
+surprising or unusual is happening in a snippet of code (for example,
+transfer of pointer ownership), leaving textual hints for the reader
+at the point of use is valuable (
std::unique_ptr+demonstrates the ownership transfer unambiguously at the call +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.
+
+ - Be consistent with the broader C++ community when appropriate +
- Consistency with the way other organizations use C++ has value for +the same reasons as consistency within our code base. If a feature in +the C++ standard solves a problem, or if some idiom is widely known +and accepted, that's an argument for using it. However, sometimes +standard features and idioms are flawed, or were just designed without +our codebase's needs in mind. In those cases (as described below) it's +appropriate to constrain or ban standard features. In some cases we +prefer a homegrown or third-party library over a library defined in +the C++ Standard, either out of perceived superiority or insufficient +value to transition the codebase to the standard interface. + +
- Avoid surprising or dangerous constructs +
- C++ has features that are more surprising or dangerous than one +might think at a glance. Some style guide restrictions are in place to +prevent falling into these pitfalls. There is a high bar for style +guide waivers on such restrictions, because waiving such rules often +directly risks compromising program correctness. + + +
- Avoid constructs that our average C++ programmer would find tricky +or hard to maintain +
- C++ has features that may not be generally appropriate because of +the complexity they introduce to the code. In widely used +code, it may be more acceptable to use +trickier language constructs, because any benefits of more complex +implementation are multiplied widely by usage, and the cost in understanding +the complexity does not need to be paid again when working with new +portions of the codebase. When in doubt, waivers to rules of this type +can be sought by asking +your project leads. This is specifically +important for our codebase because code ownership and team membership +changes over time: even if everyone that works with some piece of code +currently understands it, such understanding is not guaranteed to hold a +few years from now. + +
- Be mindful of our scale +
- With a codebase of 100+ million lines and thousands of engineers, +some mistakes and simplifications for one engineer can become costly +for many. For instance it's particularly important to +avoid polluting the global namespace: name collisions across a +codebase of hundreds of millions of lines are difficult to work with +and hard to avoid if everyone puts things into the global +namespace. + +
- Concede to optimization when necessary +
- Performance optimizations can sometimes be necessary and +appropriate, even when they conflict with the other principles of this +document. +
The intent of this document is to provide maximal guidance with +reasonable restriction. As always, common sense and good taste should +prevail. By this we specifically refer to the established conventions +of the entire Google C++ community, not just your personal preferences +or those of your team. Be skeptical about and reluctant to use +clever or unusual constructs: the absence of a prohibition is not the +same as a license to proceed. Use your judgment, and if you are +unsure, please don't hesitate to ask your project leads to get additional +input.
+ +Header Files
+ +In general, every .cc file should have an
+associated .h file. There are some common
+exceptions, such as unittests and
+small .cc files containing just a
+main() function.
Correct use of header files can make a huge difference to +the readability, size and performance of your code.
+ +The following rules will guide you through the various +pitfalls of using header files.
+ + +Self-contained Headers
+ +Header files should be self-contained (compile on their own) and
+end in .h. Non-header files that are meant for inclusion
+should end in .inc and be used sparingly.
All header files should be self-contained. Users and refactoring +tools should not have to adhere to special conditions to include the +header. Specifically, a header should +have header guards and include all +other headers it needs.
+ +Prefer placing the definitions for template and inline functions in
+the same file as their declarations. The definitions of these
+constructs must be included into every .cc file that uses
+them, or the program may fail to link in some build configurations. If
+declarations and definitions are in different files, including the
+former should transitively include the latter. Do not move these
+definitions to separately included header files (-inl.h);
+this practice was common in the past, but is no longer allowed.
As an exception, a template that is explicitly instantiated for
+all relevant sets of template arguments, or that is a private
+implementation detail of a class, is allowed to be defined in the one
+and only .cc file that instantiates the template.
There are rare cases where a file designed to be included is not
+self-contained. These are typically intended to be included at unusual
+locations, such as the middle of another file. They might not
+use header guards, and might not include
+their prerequisites. Name such files with the .inc
+extension. Use sparingly, and prefer self-contained headers when
+possible.
The #define Guard
+ +All header files should have #define guards to
+prevent multiple inclusion. The format of the symbol name
+should be
+<PROJECT>_<PATH>_<FILE>_H_.
To guarantee uniqueness, they should
+be based on the full path in a project's source tree. For
+example, the file foo/src/bar/baz.h in
+project foo should have the following
+guard:
#ifndef FOO_BAR_BAZ_H_ +#define FOO_BAR_BAZ_H_ + +... + +#endif // FOO_BAR_BAZ_H_ ++ + + + +
Forward Declarations
+ +Avoid using forward declarations where possible.
+ Just #include the headers you need.
A "forward declaration" is a declaration of a class, +function, or template without an associated definition.
+-
+
- Forward declarations can save compile time, as
+
#includes force the compiler to open + more files and process more input.
+
+ - Forward declarations can save on unnecessary
+ recompilation.
#includes can force + your code to be recompiled more often, due to unrelated + changes in the header.
+
-
+
- Forward declarations can hide a dependency, allowing + user code to skip necessary recompilation when headers + change. + +
- A forward declaration may be broken by subsequent + changes to the library. Forward declarations of functions + and templates can prevent the header owners from making + otherwise-compatible changes to their APIs, such as + widening a parameter type, adding a template parameter + with a default value, or migrating to a new namespace. + +
- Forward declaring symbols from namespace
+
std::yields undefined behavior.
+
+ - It can be difficult to determine whether a forward
+ declaration or a full
#includeis needed. + Replacing an#includewith a forward + declaration can silently change the meaning of + code: +// b.h: + struct B {}; + struct D : B {}; + + // good_user.cc: + #include "b.h" + void f(B*); + void f(void*); + void test(D* x) { f(x); } // calls f(B*) ++ If the#includewas replaced with forward + decls forBandD, +test()would callf(void*). +
+
+ - Forward declaring multiple symbols from a header
+ can be more verbose than simply
+
#includeing the header.
+
+ - Structuring code to enable forward declarations + (e.g. using pointer members instead of object members) + can make the code slower and more complex. + + +
-
+
- Try to avoid forward declarations of entities + defined in another project. + +
- When using a function declared in a header file,
+ always
#includethat header.
+
+ - When using a class template, prefer to
+
#includeits header file.
+
Please see Names and Order +of Includes for rules about when to #include a header.
+Inline Functions
+ +Define functions inline only when they are small, say, 10 +lines or fewer.
+You can declare functions in a way that allows the compiler to expand +them inline rather than calling them through the usual +function call mechanism.
+Inlining a function can generate more efficient object +code, as long as the inlined function is small. Feel free +to inline accessors and mutators, and other short, +performance-critical functions.
+Overuse of inlining can actually make programs slower. +Depending on a function's size, inlining it can cause the +code size to increase or decrease. Inlining a very small +accessor function will usually decrease code size while +inlining a very large function can dramatically increase +code size. On modern processors smaller code usually runs +faster due to better use of the instruction cache.
+A decent rule of thumb is to not inline a function if +it is more than 10 lines long. Beware of destructors, +which are often longer than they appear because of +implicit member- and base-destructor calls!
+ +Another useful rule of thumb: it's typically not cost +effective to inline functions with loops or switch +statements (unless, in the common case, the loop or +switch statement is never executed).
+ +It is important to know that functions are not always +inlined even if they are declared as such; for example, +virtual and recursive functions are not normally inlined. +Usually recursive functions should not be inline. The +main reason for making a virtual function inline is to +place its definition in the class, either for convenience +or to document its behavior, e.g., for accessors and +mutators.
+Names and Order of Includes
+ +Use standard order for readability and to avoid hidden
+dependencies: Related header, C library, C++ library, other libraries'
+.h, your project's .h.
+All of a project's header files should be
+listed as descendants of the project's source
+directory without use of UNIX directory shortcuts
+. (the current directory) or ..
+(the parent directory). For example,
+
+google-awesome-project/src/base/logging.h
+should be included as:
#include "base/logging.h" ++ +
In dir/foo.cc or
+dir/foo_test.cc, whose main
+purpose is to implement or test the stuff in
+dir2/foo2.h, order your includes
+as follows:
-
+
dir2/foo2.h.
+
+ - C system files. + +
- C++ system files. + +
- Other libraries'
.h+ files.
+
+ -
+ Your project's
.h+ files.
+
With the preferred ordering, if
+dir2/foo2.h omits any necessary
+includes, the build of dir/foo.cc
+or dir/foo_test.cc will break.
+Thus, this rule ensures that build breaks show up first
+for the people working on these files, not for innocent
+people in other packages.
dir/foo.cc and
+dir2/foo2.h are usually in the same
+directory (e.g. base/basictypes_test.cc and
+base/basictypes.h), but may sometimes be in different
+directories too.
Within each section the includes should be ordered +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. However, any
+includes present in the related header do not need to be included
+again in the related cc (i.e., foo.cc can
+rely on foo.h's includes).
For example, the includes in
+
+google-awesome-project/src/foo/internal/fooserver.cc
+might look like this:
#include "foo/server/fooserver.h" + +#include <sys/types.h> +#include <unistd.h> + +#include <hash_map> +#include <vector> + +#include "base/basictypes.h" +#include "base/commandlineflags.h" +#include "foo/server/bar.h" ++ +
Sometimes, system-specific code needs +conditional includes. Such code can put conditional +includes after other includes. Of course, keep your +system-specific code small and localized. Example:
+ +#include "foo/public/fooserver.h" + +#include "base/port.h" // For LANG_CXX11. + +#ifdef LANG_CXX11 +#include <initializer_list> +#endif // LANG_CXX11 ++ +
Scoping
+ +Namespaces
+ +With few exceptions, place code in a namespace. Namespaces
+should have unique names based on the project name, and possibly
+its path. Do not use using-directives (e.g.
+using namespace foo). Do not use
+inline namespaces. For unnamed namespaces, see
+Unnamed Namespaces and
+Static Variables.
+
Namespaces subdivide the global scope +into distinct, named scopes, and so are useful for preventing +name collisions in the global scope.
+Namespaces provide a method for preventing name conflicts +in large programs while allowing most code to use reasonably +short names.
+ +For example, if two different projects have a class
+Foo in the global scope, these symbols may
+collide at compile time or at runtime. If each project
+places their code in a namespace, project1::Foo
+and project2::Foo are now distinct symbols that
+do not collide, and code within each project's namespace
+can continue to refer to Foo without the prefix.
Inline namespaces automatically place their names in +the enclosing scope. Consider the following snippet, for +example:
+ +namespace X {
+inline namespace Y {
+ void foo();
+} // namespace Y
+} // namespace X
+
+
+The expressions X::Y::foo() and
+X::foo() are interchangeable. Inline
+namespaces are primarily intended for ABI compatibility
+across versions.
Namespaces can be confusing, because they complicate +the mechanics of figuring out what definition a name refers +to.
+ +Inline namespaces, in particular, can be confusing +because names aren't actually restricted to the namespace +where they are declared. They are only useful as part of +some larger versioning policy.
+ +In some contexts, it's necessary to repeatedly refer to +symbols by their fully-qualified names. For deeply-nested +namespaces, this can add a lot of clutter.
+Namespaces should be used as follows:
+ +-
+
- Follow the rules on Namespace Names. +
- Terminate namespaces with comments as shown in the given examples. +
-
+
+
Namespaces wrap the entire source file after + includes, + + gflags definitions/declarations + and forward declarations of classes from other namespaces.
+ +// In the .h file +namespace mynamespace { + +// All declarations are within the namespace scope. +// Notice the lack of indentation. +class MyClass { + public: + ... + void Foo(); +}; + +} // namespace mynamespace ++ +// In the .cc file +namespace mynamespace { + +// Definition of functions is within scope of the namespace. +void MyClass::Foo() { + ... +} + +} // namespace mynamespace ++ +More complex
+ +.ccfiles might have additional details, + like flags or using-declarations.#include "a.h" + +DEFINE_FLAG(bool, someflag, false, "dummy flag"); + +namespace a { + +using ::foo::bar; + +...code for a... // Code goes against the left margin. + +} // namespace a ++
+
+
+
+ - Do not declare anything in namespace
+
std, including forward declarations of + standard library classes. Declaring entities in + namespacestdis undefined behavior, i.e., + not portable. To declare entities from the standard + library, include the appropriate header file.
+
+ You may not use a using-directive + to make all names from a namespace available.
+ +// Forbidden -- This pollutes the namespace. +using namespace foo; +
+
+
+ Do not use Namespace aliases at namespace scope + in header files except in explicitly marked + internal-only namespaces, because anything imported into a namespace + in a header file becomes part of the public + API exported by that file.
+ +// Shorten access to some commonly used names in .cc files. +namespace baz = ::foo::bar::baz; +
+ +// Shorten access to some commonly used names (in a .h file). +namespace librarian { +namespace impl { // Internal, not part of the API. +namespace sidetable = ::pipeline_diagnostics::sidetable; +} // namespace impl + +inline void my_inline_function() { + // namespace alias local to a function (or method). + namespace baz = ::foo::bar::baz; + ... +} +} // namespace librarian ++ +- Do not use inline namespaces. +
Unnamed Namespaces and Static +Variables
+ +When definitions in a .cc file do not need to be
+referenced outside that file, place them in an unnamed
+namespace or declare them static. Do not use either
+of these constructs in .h files.
+
All declarations can be given internal linkage by placing them in
+unnamed namespaces, and functions and variables can be given internal linkage by
+declaring them static. This means that anything you're declaring
+can't be accessed from another file. If a different file declares something
+with the same name, then the two entities are completely independent.
Use of internal linkage in .cc files is encouraged
+for all code that does not need to be referenced elsewhere.
+Do not use internal linkage in .h files.
Format unnamed namespaces like named namespaces. In the + terminating comment, leave the namespace name empty:
+ +namespace {
+...
+} // namespace
+
+Nonmember, Static Member, and Global Functions
+ +Prefer placing nonmember functions in a namespace; use completely global +functions rarely. Prefer grouping functions with a namespace instead of +using a class as if it were a namespace. Static methods of a class should +generally be closely related to instances of the class or the class's static +data.
+Nonmember and static member functions can be useful in + some situations. Putting nonmember functions in a + namespace avoids polluting the global namespace.
+Nonmember and static member functions may make more sense +as members of a new class, especially if they access +external resources or have significant dependencies.
+Sometimes it is useful to define a
+function not bound to a class instance. Such a function
+can be either a static member or a nonmember function.
+Nonmember functions should not depend on external
+variables, and should nearly always exist in a namespace.
+Rather than creating classes only to group static member
+functions which do not share static data, use
+namespaces instead. For a header
+myproject/foo_bar.h, for example, write
namespace myproject {
+namespace foo_bar {
+void Function1();
+void Function2();
+} // namespace foo_bar
+} // namespace myproject
+
+instead of
+namespace myproject {
+class FooBar {
+ public:
+ static void Function1();
+ static void Function2();
+};
+} // namespace myproject
+
+
+If you define a nonmember function and it is only
+needed in its .cc file, use
+internal linkage to limit
+its scope.
Local Variables
+ +Place a function's variables in the narrowest scope +possible, and initialize variables in the declaration.
+C++ allows you to declare variables anywhere in a +function. We encourage you to declare them in as local a +scope as possible, and as close to the first use as +possible. This makes it easier for the reader to find the +declaration and see what type the variable is and what it +was initialized to. In particular, initialization should +be used instead of declaration and assignment, e.g.:
+ +int i; +i = f(); // Bad -- initialization separate from declaration. ++ +
int j = g(); // Good -- declaration has initialization. ++ +
std::vector<int> v; +v.push_back(1); // Prefer initializing using brace initialization. +v.push_back(2); ++ +
std::vector<int> v = {1, 2}; // Good -- v starts initialized.
+
+
+Variables needed for if, while
+and for statements should normally be declared
+within those statements, so that such variables are confined
+to those scopes. E.g.:
while (const char* p = strchr(str, '/')) str = p + 1; ++ +
There is one caveat: if the variable is an object, its +constructor is invoked every time it enters scope and is +created, and its destructor is invoked every time it goes +out of scope.
+ +// Inefficient implementation:
+for (int i = 0; i < 1000000; ++i) {
+ Foo f; // My ctor and dtor get called 1000000 times each.
+ f.DoSomething(i);
+}
+
+
+It may be more efficient to declare such a variable +used in a loop outside that loop:
+ +Foo f; // My ctor and dtor get called once each.
+for (int i = 0; i < 1000000; ++i) {
+ f.DoSomething(i);
+}
+
+
+Static and Global Variables
+ +Variables of class type with
+ static storage duration are forbidden: they cause hard-to-find bugs due
+ to indeterminate order of construction and destruction. However, such
+ variables are allowed if they are constexpr: they have no
+ dynamic initialization or destruction.
Objects with static storage duration, including global +variables, static variables, static class member +variables, and function static variables, must be Plain +Old Data (POD): only ints, chars, floats, or pointers, or +arrays/structs of POD.
+ +The order in which class constructors and initializers +for static variables are called is only partially +specified in C++ and can even change from build to build, +which can cause bugs that are difficult to find. +Therefore in addition to banning globals of class type, +we do not allow non-local static variables to be initialized +with the result of a function, unless that function (such +as getenv(), or getpid()) does not itself depend on any +other globals. However, a static POD variable within +function scope may be initialized with the result of a +function, since its initialization order is well-defined +and does not occur until control passes through its +declaration.
+ +Likewise, global and static variables are destroyed
+when the program terminates, regardless of whether the
+termination is by returning from main() or
+by calling exit(). The order in which
+destructors are called is defined to be the reverse of
+the order in which the constructors were called. Since
+constructor order is indeterminate, so is destructor
+order. For example, at program-end time a static variable
+might have been destroyed, but code still running
+— perhaps in another thread
+— tries to access it and fails. Or the
+destructor for a static string variable
+might be run prior to the destructor for another variable
+that contains a reference to that string.
One way to alleviate the destructor problem is to
+terminate the program by calling
+quick_exit() instead of exit().
+The difference is that quick_exit() does not
+invoke destructors and does not invoke any handlers that
+were registered by calling atexit(). If you
+have a handler that needs to run when a program
+terminates via quick_exit() (flushing logs,
+for example), you can register it using
+at_quick_exit(). (If you have a handler that
+needs to run at both exit() and
+quick_exit(), you need to register it in
+both places.)
As a result we only allow static variables to contain
+POD data. This rule completely disallows
+std::vector (use C arrays instead), or
+string (use const char []).
If you need a static or global +variable of a class type, consider initializing a pointer +(which will never be freed), from either your main() +function or from pthread_once(). Note that this must be a +raw pointer, not a "smart" pointer, since the smart +pointer's destructor will have the order-of-destructor +issue that we are trying to avoid.
+ + + + + +Classes
+ +Classes are the fundamental unit of code in C++. Naturally, +we use them extensively. This section lists the main dos and +don'ts you should follow when writing a class.
+ +Doing Work in Constructors
+ +Avoid virtual method calls in constructors, and avoid +initialization that can fail if you can't signal an error.
+It is possible to perform arbitrary initialization in the body +of the constructor.
+-
+
- No need to worry about whether the class has been initialized or + not. + +
- Objects that are fully initialized by constructor call can
+ be
constand may also be easier to use with standard containers + or algorithms.
+
-
+
- If the work calls virtual functions, these calls + will not get dispatched to the subclass + implementations. Future modification to your class can + quietly introduce this problem even if your class is + not currently subclassed, causing much confusion. + +
- There is no easy way for constructors to signal errors, short of + crashing the program (not always appropriate) or using exceptions + (which are forbidden). + +
- If the work fails, we now have an object whose initialization
+ code failed, so it may be an unusual state requiring a
bool + IsValid()state checking mechanism (or similar) which is easy + to forget to call.
+
+ - You cannot take the address of a constructor, so whatever work + is done in the constructor cannot easily be handed off to, for + example, another thread. +
Constructors should never call virtual functions. If appropriate
+for your code
+,
+terminating the program may be an appropriate error handling
+response. Otherwise, consider a factory function
+or Init() method. Avoid Init() methods on objects with
+no other states that affect which public methods may be called
+(semi-constructed objects of this form are particularly hard to work
+with correctly).
Implicit Conversions
+ +Do not define implicit conversions. Use the explicit
+keyword for conversion operators and single-argument
+constructors.
Implicit conversions allow an
+object of one type (called the source type) to
+be used where a different type (called the destination
+type) is expected, such as when passing an
+int argument to a function that takes a
+double parameter.
In addition to the implicit conversions defined by the language,
+users can define their own, by adding appropriate members to the
+class definition of the source or destination type. An implicit
+conversion in the source type is defined by a type conversion operator
+named after the destination type (e.g. operator
+bool()). An implicit conversion in the destination
+type is defined by a constructor that can take the source type as
+its only argument (or only argument with no default value).
The explicit keyword can be applied to a constructor
+or (since C++11) a conversion operator, to ensure that it can only be
+used when the destination type is explicit at the point of use,
+e.g. with a cast. This applies not only to implicit conversions, but to
+C++11's list initialization syntax:
class Foo {
+ explicit Foo(int x, double y);
+ ...
+};
+
+void Func(Foo f);
+
+Func({42, 3.14}); // Error
+
+This kind of code isn't technically an implicit conversion, but the
+language treats it as one as far as explicit is concerned.
+-
+
- Implicit conversions can make a type more usable and + expressive by eliminating the need to explicitly name a type + when it's obvious. +
- Implicit conversions can be a simpler alternative to + overloading. +
- List initialization syntax is a concise and expressive + way of initializing objects. +
-
+
- Implicit conversions can hide type-mismatch bugs, where the + destination type does not match the user's expectation, or + the user is unaware that any conversion will take place. + +
- Implicit conversions can make code harder to read, particularly + in the presence of overloading, by making it less obvious what + code is actually getting called. + +
- Constructors that take a single argument may accidentally + be usable as implicit type conversions, even if they are not + intended to do so. + +
- When a single-argument constructor is not marked
+
explicit, there's no reliable way to tell whether + it's intended to define an implicit conversion, or the author + simply forgot to mark it.
+
+ - It's not always clear which type should provide the conversion, + and if they both do, the code becomes ambiguous. + +
- List initialization can suffer from the same problems if + the destination type is implicit, particularly if the + list has only a single element. +
Type conversion operators, and constructors that are
+callable with a single argument, must be marked
+explicit in the class definition. As an
+exception, copy and move constructors should not be
+explicit, since they do not perform type
+conversion. Implicit conversions can sometimes be necessary and
+appropriate for types that are designed to transparently wrap other
+types. In that case, contact
+your project leads to request
+a waiver of this rule.
Constructors that cannot be called with a single argument
+should usually omit explicit. Constructors that
+take a single std::initializer_list parameter should
+also omit explicit, in order to support copy-initialization
+(e.g. MyType m = {1, 2};).
Copyable and Movable Types
+ +Support copying and/or moving if these operations are clear and meaningful +for your type. Otherwise, disable the implicitly generated special functions +that perform copies and moves. +
A copyable type allows its objects to be initialized or assigned
+from any other object of the same type, without changing the value of the source.
+For user-defined types, the copy behavior is defined by the copy
+constructor and the copy-assignment operator.
+string is an example of a copyable type.
A movable type is one that can be initialized and assigned
+from temporaries (all copyable types are therefore movable).
+std::unique_ptr<int> is an example of a movable but not
+copyable type. For user-defined types, the move behavior is defined by the move
+constructor and the move-assignment operator.
The copy/move constructors can be implicitly invoked by the compiler +in some situations, e.g. when passing objects by value.
+Objects of copyable and movable types can be passed and returned by value, +which makes APIs simpler, safer, and more general. Unlike when passing objects +by pointer or reference, there's no risk of confusion over ownership, +lifetime, mutability, and similar issues, and no need to specify them in the +contract. It also prevents non-local interactions between the client and the +implementation, which makes them easier to understand, maintain, and optimize by +the compiler. Further, such objects can be used with generic APIs that +require pass-by-value, such as most containers, and they allow for additional +flexibility in e.g., type composition.
+ +Copy/move constructors and assignment operators are usually
+easier to define correctly than alternatives
+like Clone(), CopyFrom() or Swap(),
+because they can be generated by the compiler, either implicitly or
+with = default. They are concise, and ensure
+that all data members are copied. Copy and move
+constructors are also generally more efficient, because they don't
+require heap allocation or separate initialization and assignment
+steps, and they're eligible for optimizations such as
+
+
+copy elision.
Move operations allow the implicit and efficient transfer of +resources out of rvalue objects. This allows a plainer coding style +in some cases.
+Some types do not need to be copyable, and providing copy
+operations for such types can be confusing, nonsensical, or outright
+incorrect. Types representing singleton objects (Registerer),
+objects tied to a specific scope (Cleanup), or closely coupled to
+object identity (Mutex) cannot be copied meaningfully.
+Copy operations for base class types that are to be used
+polymorphically are hazardous, because use of them can lead to
+object slicing.
+Defaulted or carelessly-implemented copy operations can be incorrect, and the
+resulting bugs can be confusing and difficult to diagnose.
Copy constructors are invoked implicitly, which makes the +invocation easy to miss. This may cause confusion for programmers used to +languages where pass-by-reference is conventional or mandatory. It may also +encourage excessive copying, which can cause performance problems.
+Provide the copy and move operations if their meaning is clear to a casual +user and the copying/moving does not incur unexpected costs. If you define a +copy or move constructor, define the corresponding assignment operator, and +vice-versa. If your type is copyable, do not define move operations unless they +are significantly more efficient than the corresponding copy operations. If your +type is not copyable, but the correctness of a move is obvious to users of the +type, you may make the type move-only by defining both of the move operations. +
+ +If your type provides copy operations, it is recommended that you design +your class so that the default implementation of those operations is correct. +Remember to review the correctness of any defaulted operations as you would any +other code, and to document that your class is copyable and/or cheaply movable +if that's an API guarantee.
+ +class Foo {
+ public:
+ Foo(Foo&& other) : field_(other.field) {}
+ // Bad, defines only move constructor, but not operator=.
+
+ private:
+ Field field_;
+};
+
+
+Due to the risk of slicing, avoid providing an assignment
+operator or public copy/move constructor for a class that's
+intended to be derived from (and avoid deriving from a class
+with such members). If your base class needs to be
+copyable, provide a public virtual Clone()
+method, and a protected copy constructor that derived classes
+can use to implement it.
If you do not want to support copy/move operations on your type,
+explicitly disable them using = delete in
+the public: section:
// MyClass is neither copyable nor movable. +MyClass(const MyClass&) = delete; +MyClass& operator=(const MyClass&) = delete; ++ + + +
Structs vs. Classes
+ +Use a struct only for passive objects that
+ carry data; everything else is a class.
The struct and class
+keywords behave almost identically in C++. We add our own
+semantic meanings to each keyword, so you should use the
+appropriate keyword for the data-type you're
+defining.
structs should be used for passive
+objects that carry data, and may have associated
+constants, but lack any functionality other than
+access/setting the data members. The accessing/setting of
+fields is done by directly accessing the fields rather
+than through method invocations. Methods should not
+provide behavior but should only be used to set up the
+data members, e.g., constructor, destructor,
+Initialize(), Reset(),
+Validate().
If more functionality is required, a
+class is more appropriate. If in doubt, make
+it a class.
For consistency with STL, you can use
+struct instead of class for
+functors and traits.
Note that member variables in structs and classes have +different naming rules.
+ +Inheritance
+ +Composition is often more appropriate than inheritance.
+When using inheritance, make it public.
When a sub-class +inherits from a base class, it includes the definitions +of all the data and operations that the parent base class +defines. In practice, inheritance is used in two major +ways in C++: implementation inheritance, in which actual +code is inherited by the child, and +interface inheritance, in which +only method names are inherited.
+Implementation inheritance reduces code size by re-using +the base class code as it specializes an existing type. +Because inheritance is a compile-time declaration, you +and the compiler can understand the operation and detect +errors. Interface inheritance can be used to +programmatically enforce that a class expose a particular +API. Again, the compiler can detect errors, in this case, +when a class does not define a necessary method of the +API.
+For implementation inheritance, because the code +implementing a sub-class is spread between the base and +the sub-class, it can be more difficult to understand an +implementation. The sub-class cannot override functions +that are not virtual, so the sub-class cannot change +implementation. The base class may also define some data +members, so that specifies physical layout of the base +class.
+All inheritance should be public. If you
+want to do private inheritance, you should be including
+an instance of the base class as a member instead.
Do not overuse implementation inheritance. Composition
+is often more appropriate. Try to restrict use of
+inheritance to the "is-a" case: Bar
+subclasses Foo if it can reasonably be said
+that Bar "is a kind of"
+Foo.
Make your destructor virtual if
+necessary. If your class has virtual methods, its
+destructor should be virtual.
Limit the use of protected to those
+member functions that might need to be accessed from
+subclasses. Note that data
+members should be private.
Explicitly annotate overrides of virtual functions
+or virtual destructors with an override
+or (less frequently) final specifier.
+Older (pre-C++11) code will use the
+virtual keyword as an inferior
+alternative annotation. For clarity, use exactly one of
+override, final, or
+virtual when declaring an override.
+Rationale: A function or destructor marked
+override or final that is
+not an override of a base class virtual function will
+not compile, and this helps catch common errors. The
+specifiers serve as documentation; if no specifier is
+present, the reader has to check all ancestors of the
+class in question to determine if the function or
+destructor is virtual or not.
Multiple Inheritance
+ +Only very rarely is multiple implementation inheritance
+actually useful. We allow multiple inheritance only when at
+most one of the base classes has an implementation; all
+other base classes must be pure
+interface classes tagged with the
+Interface suffix.
Multiple inheritance allows a sub-class to have more than +one base class. We distinguish between base classes that are +pure interfaces and those that have an +implementation.
+Multiple implementation inheritance may let you re-use +even more code than single inheritance (see Inheritance).
+Only very rarely is multiple implementation +inheritance actually useful. When multiple implementation +inheritance seems like the solution, you can usually find +a different, more explicit, and cleaner solution.
+ Multiple inheritance is allowed only when all
+superclasses, with the possible exception of the first one,
+are pure interfaces. In order to
+ensure that they remain pure interfaces, they must end with
+the Interface suffix.
There is an exception to +this rule on Windows.
+Interfaces
+ +Classes that satisfy certain conditions are allowed, but
+not required, to end with an Interface suffix.
A class is a pure interface if it meets the following +requirements:
+ +-
+
- It has only public pure virtual ("
= + 0") methods and static methods (but see below + for destructor).
+
+ - It may not have non-static data members. + +
- It need not have any constructors defined. If a + constructor is provided, it must take no arguments and + it must be protected. + +
- If it is a subclass, it may only be derived from
+ classes that satisfy these conditions and are tagged
+ with the
Interfacesuffix.
+
An interface class can never be directly instantiated +because of the pure virtual method(s) it declares. To +make sure all implementations of the interface can be +destroyed correctly, the interface must also declare a +virtual destructor (in an exception to the first rule, +this should not be pure). See Stroustrup, The C++ +Programming Language, 3rd edition, section 12.4 +for details.
+Tagging a class with the Interface suffix
+lets others know that they must not add implemented
+methods or non static data members. This is particularly
+important in the case of multiple inheritance.
+Additionally, the interface concept is already
+well-understood by Java programmers.
The Interface suffix lengthens the class
+name, which can make it harder to read and understand.
+Also, the interface property may be considered an
+implementation detail that shouldn't be exposed to
+clients.
A class may end
+with Interface only if it meets the above
+requirements. We do not require the converse, however:
+classes that meet the above requirements are not required
+to end with Interface.
Operator Overloading
+ +Overload operators judiciously. Do not create user-defined literals.
+C++ permits user code to
+declare
+overloaded versions of the built-in operators using the
+operator keyword, so long as one of the parameters
+is a user-defined type. The operator keyword also
+permits user code to define new kinds of literals using
+operator"", and to define type-conversion functions
+such as operator bool().
Operator overloading can make code more concise and
+intuitive by enabling user-defined types to behave the same
+as built-in types. Overloaded operators are the idiomatic names
+for certain operations (e.g. ==, <,
+=, and <<), and adhering to
+those conventions can make user-defined types more readable
+and enable them to interoperate with libraries that expect
+those names.
User-defined literals are a very concise notation for +creating objects of user-defined types.
+-
+
- Providing a correct, consistent, and unsurprising + set of operator overloads requires some care, and failure + to do so can lead to confusion and bugs. + +
- Overuse of operators can lead to obfuscated code, + particularly if the overloaded operator's semantics + don't follow convention. + +
- The hazards of function overloading apply just as + much to operator overloading, if not more so. + +
- Operator overloads can fool our intuition into + thinking that expensive operations are cheap, built-in + operations. + +
- Finding the call sites for overloaded operators may + require a search tool that's aware of C++ syntax, rather + than e.g. grep. + +
- If you get the argument type of an overloaded operator
+ wrong, you may get a different overload rather than a
+ compiler error. For example,
foo < bar+ may do one thing, while&foo < &bar+ does something totally different.
+
+ - Certain operator overloads are inherently hazardous.
+ Overloading unary
&can cause the same + code to have different meanings depending on whether + the overload declaration is visible. Overloads of +&&,||, and,+ (comma) cannot match the evaluation-order semantics of the + built-in operators.
+
+ - Operators are often defined outside the class, + so there's a risk of different files introducing + different definitions of the same operator. If both + definitions are linked into the same binary, this results + in undefined behavior, which can manifest as subtle + run-time bugs. + +
- User-defined literals allow the creation of new + syntactic forms that are unfamiliar even to experienced C++ + programmers. +
Define overloaded operators only if their meaning is
+obvious, unsurprising, and consistent with the corresponding
+built-in operators. For example, use | as a
+bitwise- or logical-or, not as a shell-style pipe.
Define operators only on your own types. More precisely,
+define them in the same headers, .cc files, and namespaces
+as the types they operate on. That way, the operators are available
+wherever the type is, minimizing the risk of multiple
+definitions. If possible, avoid defining operators as templates,
+because they must satisfy this rule for any possible template
+arguments. If you define an operator, also define
+any related operators that make sense, and make sure they
+are defined consistently. For example, if you overload
+<, overload all the comparison operators,
+and make sure < and > never
+return true for the same arguments.
Prefer to define non-modifying binary operators as
+non-member functions. If a binary operator is defined as a
+class member, implicit conversions will apply to the
+right-hand argument, but not the left-hand one. It will
+confuse your users if a < b compiles but
+b < a doesn't.
Don't go out of your way to avoid defining operator
+overloads. For example, prefer to define ==,
+=, and <<, rather than
+Equals(), CopyFrom(), and
+PrintTo(). Conversely, don't define
+operator overloads just because other libraries expect
+them. For example, if your type doesn't have a natural
+ordering, but you want to store it in a std::set,
+use a custom comparator rather than overloading
+<.
Do not overload &&, ||,
+, (comma), or unary &. Do not overload
+operator"", i.e. do not introduce user-defined
+literals.
Type conversion operators are covered in the section on
+implicit conversions.
+The = operator is covered in the section on
+copy constructors. Overloading
+<< for use with streams is covered in the
+section on streams. See also the rules on
+function overloading, which
+apply to operator overloading as well.
Access Control
+ + Make data members private, unless they are
+static const (and follow the
+naming convention for constants). For technical
+reasons, we allow data members of a test fixture class to
+be protected when using
+
+
+Google
+Test).
Declaration Order
+ +Group similar declarations together, placing public parts +earlier.
+A class definition should usually start with a
+public: section, followed by
+protected:, then private:. Omit
+sections that would be empty.
Within each section, generally prefer grouping similar
+kinds of declarations together, and generally prefer the
+following order: types (including typedef,
+using, and nested structs and classes),
+constants, factory functions, constructors, assignment
+operators, destructor, all other methods, data members.
Do not put large method definitions inline in the +class definition. Usually, only trivial or +performance-critical, and very short, methods may be +defined inline. See Inline +Functions for more details.
+ +Functions
+ +Parameter Ordering
+ +When defining a function, parameter order is: inputs, then +outputs.
+Parameters to C/C++ functions are either input to the
+function, output from the function, or both. Input
+parameters are usually values or const
+references, while output and input/output parameters will
+be pointers to non-const. When ordering
+function parameters, put all input-only parameters before
+any output parameters. In particular, do not add new
+parameters to the end of the function just because they
+are new; place new input-only parameters before the
+output parameters.
This is not a hard-and-fast rule. Parameters that are +both input and output (often classes/structs) muddy the +waters, and, as always, consistency with related +functions may require you to bend the rule.
+ +Write Short Functions
+ +Prefer small and focused functions.
+We recognize that long functions are sometimes +appropriate, so no hard limit is placed on functions +length. If a function exceeds about 40 lines, think about +whether it can be broken up without harming the structure +of the program.
+ +Even if your long function works perfectly now, +someone modifying it in a few months may add new +behavior. This could result in bugs that are hard to +find. Keeping your functions short and simple makes it +easier for other people to read and modify your code.
+ +You could find long and complicated functions when +working with +some code. Do not be +intimidated by modifying existing code: if working with +such a function proves to be difficult, you find that +errors are hard to debug, or you want to use a piece of +it in several different contexts, consider breaking up +the function into smaller and more manageable pieces.
+ +Reference Arguments
+ +All parameters passed by reference must be labeled
+const.
In C, if a
+function needs to modify a variable, the parameter must
+use a pointer, eg int foo(int *pval). In
+C++, the function can alternatively declare a reference
+parameter: int foo(int &val).
Defining a parameter as reference avoids ugly code like
+(*pval)++. Necessary for some applications
+like copy constructors. Makes it clear, unlike with
+pointers, that a null pointer is not a possible
+value.
References can be confusing, as they have value syntax +but pointer semantics.
+Within function parameter lists all references must be
+const:
void Foo(const string &in, string *out); ++ +
In fact it is a very strong convention in Google code
+that input arguments are values or const
+references while output arguments are pointers. Input
+parameters may be const pointers, but we
+never allow non-const reference parameters
+except when required by convention, e.g.,
+swap().
However, there are some instances where using
+const T* is preferable to const
+T& for input parameters. For example:
-
+
- You want to pass in a null pointer. + +
- The function saves a pointer or reference to the + input. +
Remember that most of the time input
+parameters are going to be specified as const
+T&. Using const T* instead
+communicates to the reader that the input is somehow
+treated differently. So if you choose const
+T* rather than const T&, do so
+for a concrete reason; otherwise it will likely confuse
+readers by making them look for an explanation that
+doesn't exist.
Function Overloading
+ +Use overloaded functions (including constructors) only if a +reader looking at a call site can get a good idea of what +is happening without having to first figure out exactly +which overload is being called.
+You may write a function that takes a const
+string& and overload it with another that
+takes const char*.
class MyClass {
+ public:
+ void Analyze(const string &text);
+ void Analyze(const char *text, size_t textlen);
+};
+
+Overloading can make code more intuitive by allowing an +identically-named function to take different arguments. +It may be necessary for templatized code, and it can be +convenient for Visitors.
+If a function is overloaded by the argument types alone, +a reader may have to understand C++'s complex matching +rules in order to tell what's going on. Also many people +are confused by the semantics of inheritance if a derived +class overrides only some of the variants of a +function.
+If you want to overload a function, consider qualifying
+the name with some information about the arguments, e.g.,
+AppendString(), AppendInt()
+rather than just Append(). If you are
+overloading a function to support variable number of
+arguments of the same type, consider making it take a
+std::vector so that the user can use an
+initializer list
+ to specify the arguments.
Default Arguments
+ +Default arguments are allowed on non-virtual functions +when the default is guaranteed to always have the same +value. Follow the same restrictions as for function overloading, and +prefer overloaded functions if the readability gained with +default arguments doesn't outweigh the downsides below.
+Often you have a function that uses default values, but +occasionally you want to override the defaults. Default +parameters allow an easy way to do this without having to +define many functions for the rare exceptions. Compared +to overloading the function, default arguments have a +cleaner syntax, with less boilerplate and a clearer +distinction between 'required' and 'optional' +arguments.
+Defaulted arguments are another way to achieve the +semantics of overloaded functions, so all the reasons not to overload +functions apply.
+ +The defaults for arguments in a virtual function call are +determined by the static type of the target object, and +there's no guarantee that all overrides of a given function +declare the same defaults.
+ +Default parameters are re-evaluated at each call site, +which can bloat the generated code. Readers may also expect +the default's value to be fixed at the declaration instead +of varying at each call.
+ +Function pointers are confusing in the presence of +default arguments, since the function signature often +doesn't match the call signature. Adding +function overloads avoids these problems.
+Default arguments are banned on virtual functions, where
+they don't work properly, and in cases where the specified
+default might not evaluate to the same value depending on
+when it was evaluated. (For example, don't write void
+f(int n = counter++);.)
In some other cases, default arguments can improve the +readability of their function declarations enough to +overcome the downsides above, so they are allowed. When in +doubt, use overloads.
+Trailing Return Type Syntax
+Use trailing return types only where using the ordinary syntax (leading + return types) is impractical or much less readable.
+C++ allows two different forms of function declarations. In the older + form, the return type appears before the function name. For example:
+int foo(int x); ++
The new form, introduced in C++11, uses the auto
+ keyword before the function name and a trailing return type after
+ the argument list. For example, the declaration above could
+ equivalently be written:
auto foo(int x) -> int; ++
The trailing return type is in the function's scope. This doesn't
+ make a difference for a simple case like int but it matters
+ for more complicated cases, like types declared in class scope or
+ types written in terms of the function parameters.
Trailing return types are the only way to explicitly specify the + return type of a lambda expression. + In some cases the compiler is able to deduce a lambda's return type, + but not in all cases. Even when the compiler can deduce it automatically, + sometimes specifying it explicitly would be clearer for readers. +
+Sometimes it's easier and more readable to specify a return type + after the function's parameter list has already appeared. This is + particularly true when the return type depends on template parameters. + For example:
+template <class T, class U> auto add(T t, U u) -> decltype(t + u);+ versus +
template <class T, class U> decltype(declval<T&>() + declval<U&>()) add(T t, U u);+
Trailing return type syntax is relatively new and it has no + analogue in C++-like languages like C and Java, so some readers may + find it unfamiliar.
+Existing code bases have an enormous number of function + declarations that aren't going to get changed to use the new syntax, + so the realistic choices are using the old syntax only or using a mixture + of the two. Using a single version is better for uniformity of style.
+In most cases, continue to use the older style of function + declaration where the return type goes before the function name. + Use the new trailing-return-type form only in cases where it's + required (such as lambdas) or where, by putting the type after the + function's parameter list, it allows you to write the type in a much + more readable way. The latter case should be rare; it's mostly an + issue in fairly complicated template code, which is + discouraged in most cases.
+ +Google-Specific Magic
+ + + +There are various tricks and utilities that +we use to make C++ code more robust, and various ways we use +C++ that may differ from what you see elsewhere.
+ + + +Ownership and Smart Pointers
+ +Prefer to have single, fixed owners for dynamically +allocated objects. Prefer to transfer ownership with smart +pointers.
+"Ownership" is a bookkeeping technique for managing +dynamically allocated memory (and other resources). The +owner of a dynamically allocated object is an object or +function that is responsible for ensuring that it is +deleted when no longer needed. Ownership can sometimes be +shared, in which case the last owner is typically +responsible for deleting it. Even when ownership is not +shared, it can be transferred from one piece of code to +another.
+ +"Smart" pointers are classes that act like pointers,
+e.g. by overloading the * and
+-> operators. Some smart pointer types
+can be used to automate ownership bookkeeping, to ensure
+these responsibilities are met.
+
+std::unique_ptr is a smart pointer type
+introduced in C++11, which expresses exclusive ownership
+of a dynamically allocated object; the object is deleted
+when the std::unique_ptr goes out of scope.
+It cannot be copied, but can be moved to
+represent ownership transfer.
+
+std::shared_ptr is a smart pointer type
+that expresses shared ownership of
+a dynamically allocated object. std::shared_ptrs
+can be copied; ownership of the object is shared among
+all copies, and the object is deleted when the last
+std::shared_ptr is destroyed.
-
+
- It's virtually impossible to manage dynamically + allocated memory without some sort of ownership + logic. + +
- Transferring ownership of an object can be cheaper + than copying it (if copying it is even possible). + +
- Transferring ownership can be simpler than + 'borrowing' a pointer or reference, because it reduces + the need to coordinate the lifetime of the object + between the two users. + +
- Smart pointers can improve readability by making + ownership logic explicit, self-documenting, and + unambiguous. + +
- Smart pointers can eliminate manual ownership + bookkeeping, simplifying the code and ruling out large + classes of errors. + +
- For const objects, shared ownership can be a simple + and efficient alternative to deep copying. +
-
+
- Ownership must be represented and transferred via + pointers (whether smart or plain). Pointer semantics + are more complicated than value semantics, especially + in APIs: you have to worry not just about ownership, + but also aliasing, lifetime, and mutability, among + other issues. + +
- The performance costs of value semantics are often + overestimated, so the performance benefits of ownership + transfer might not justify the readability and + complexity costs. + +
- APIs that transfer ownership force their clients + into a single memory management model. + +
- Code using smart pointers is less explicit about + where the resource releases take place. + +
std::unique_ptrexpresses ownership + transfer using C++11's move semantics, which are + relatively new and may confuse some programmers.
+
+ - Shared ownership can be a tempting alternative to + careful ownership design, obfuscating the design of a + system. + +
- Shared ownership requires explicit bookkeeping at + run-time, which can be costly. + +
- In some cases (e.g. cyclic references), objects + with shared ownership may never be deleted. + +
- Smart pointers are not perfect substitutes for + plain pointers. +
If dynamic allocation is necessary, prefer to keep
+ownership with the code that allocated it. If other code
+needs access to the object, consider passing it a copy,
+or passing a pointer or reference without transferring
+ownership. Prefer to use std::unique_ptr to
+make ownership transfer explicit. For example:
std::unique_ptr<Foo> FooFactory(); +void FooConsumer(std::unique_ptr<Foo> ptr); ++ + + +
Do not design your code to use shared ownership
+without a very good reason. One such reason is to avoid
+expensive copy operations, but you should only do this if
+the performance benefits are significant, and the
+underlying object is immutable (i.e.
+std::shared_ptr<const Foo>). If you
+do use shared ownership, prefer to use
+std::shared_ptr.
Never use std::auto_ptr. Instead, use
+std::unique_ptr.
cpplint
+ +Use cpplint.py
+to detect style errors.
cpplint.py
+is a tool that reads a source file and 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 can be ignored by putting //
+NOLINT at the end of the line or
+// NOLINTNEXTLINE in the previous line.
Some projects have instructions on
+how to run cpplint.py from their project
+tools. If the project you are contributing to does not,
+you can download
+
+cpplint.py separately.
Other C++ Features
+ +Rvalue References
+ +Use rvalue references only to define move constructors and move assignment +operators, or for perfect forwarding. +
+ Rvalue references
+are a type of reference that can only bind to temporary
+objects. The syntax is similar to traditional reference
+syntax. For example, void f(string&&
+s); declares a function whose argument is an
+rvalue reference to a string.
-
+
- Defining a move constructor (a constructor taking
+ an rvalue reference to the class type) makes it
+ possible to move a value instead of copying it. If
+
v1is astd::vector<string>, + for example, thenauto v2(std::move(v1))+ will probably just result in some simple pointer + manipulation instead of copying a large amount of data. + In some cases this can result in a major performance + improvement.
+
+ - Rvalue references make it possible to write a + generic function wrapper that forwards its arguments to + another function, and works whether or not its + arguments are temporary objects. (This is sometimes called + "perfect forwarding".) + +
- Rvalue references make it possible to implement + types that are movable but not copyable, which can be + useful for types that have no sensible definition of + copying but where you might still want to pass them as + function arguments, put them in containers, etc. + +
std::moveis necessary to make + effective use of some standard-library types, such as +std::unique_ptr.
+
-
+
- Rvalue references are a relatively new feature + (introduced as part of C++11), and not yet widely + understood. Rules like reference collapsing, and + automatic synthesis of move constructors, are + complicated. +
Use rvalue references only to define move constructors and move assignment
+ operators (as described in Copyable and
+ Movable Types) and, in conjunction with std::forward,
+to support perfect forwarding. You may use std::move to express
+moving a value from one object to another rather than copying it.
Friends
+ +We allow use of friend classes and functions,
+within reason.
Friends should usually be defined in the same file so
+that the reader does not have to look in another file to
+find uses of the private members of a class. A common use
+of friend is to have a
+FooBuilder class be a friend of
+Foo so that it can construct the inner state
+of Foo correctly, without exposing this
+state to the world. In some cases it may be useful to
+make a unittest class a friend of the class it tests.
Friends extend, but do not break, the encapsulation +boundary of a class. In some cases this is better than +making a member public when you want to give only one +other class access to it. However, most classes should +interact with other classes solely through their public +members.
+ +Exceptions
+ +We do not use C++ exceptions.
+-
+
- Exceptions allow higher levels of an application to + decide how to handle "can't happen" failures in deeply + nested functions, without the obscuring and error-prone + bookkeeping of error codes. + + + +
- Exceptions are used by most other + modern languages. Using them in C++ would make it more + consistent with Python, Java, and the C++ that others + are familiar with. + +
- Some third-party C++ libraries use exceptions, and + turning them off internally makes it harder to + integrate with those libraries. + +
- Exceptions are the only way for a constructor to
+ fail. We can simulate this with a factory function or
+ an
Init()method, but these require heap + allocation or a new "invalid" state, respectively.
+
+ - Exceptions are really handy in testing + frameworks. +
-
+
- When you add a
throwstatement to an + existing function, you must examine all of its + transitive callers. Either they must make at least the + basic exception safety guarantee, or they must never + catch the exception and be happy with the program + terminating as a result. For instance, if +f()callsg()calls +h(), andhthrows an + exception thatfcatches,g+ has to be careful or it may not clean up properly.
+
+ - More generally, exceptions make the control flow of + programs difficult to evaluate by looking at code: + functions may return in places you don't expect. This + causes maintainability and debugging difficulties. You + can minimize this cost via some rules on how and where + exceptions can be used, but at the cost of more that a + developer needs to know and understand. + +
- Exception safety requires both RAII and different + coding practices. Lots of supporting machinery is + needed to make writing correct exception-safe code + easy. Further, to avoid requiring readers to understand + the entire call graph, exception-safe code must isolate + logic that writes to persistent state into a "commit" + phase. This will have both benefits and costs (perhaps + where you're forced to obfuscate code to isolate the + commit). Allowing exceptions would force us to always + pay those costs even when they're not worth it. + +
- Turning on exceptions adds data to each binary + produced, increasing compile time (probably slightly) + and possibly increasing address space pressure. + + +
- The availability of exceptions may encourage + developers to throw them when they are not appropriate + or recover from them when it's not safe to do so. For + example, invalid user input should not cause exceptions + to be thrown. We would need to make the style guide + even longer to document these restrictions! +
On their face, the benefits of using exceptions +outweigh the costs, especially in new projects. However, +for existing code, the introduction of exceptions has +implications on all dependent code. If exceptions can be +propagated beyond a new project, it also becomes +problematic to integrate the new project into existing +exception-free code. Because most existing C++ code at +Google is not prepared to deal with exceptions, it is +comparatively difficult to adopt new code that generates +exceptions.
+ +Given that Google's existing code is not +exception-tolerant, the costs of using exceptions are +somewhat greater than the costs in a new project. The +conversion process would be slow and error-prone. We +don't believe that the available alternatives to +exceptions, such as error codes and assertions, introduce +a significant burden.
+ +Our advice against using exceptions is not predicated +on philosophical or moral grounds, but practical ones. + Because we'd like to use our open-source +projects at Google and it's difficult to do so if those +projects use exceptions, we need to advise against +exceptions in Google open-source projects as well. +Things would probably be different if we had to do it all +over again from scratch.
+ +This prohibition also applies to the exception-related
+features added in C++11, such as noexcept,
+std::exception_ptr, and
+std::nested_exception.
There is an exception to +this rule (no pun intended) for Windows code.
+Run-Time Type +Information (RTTI)
+ +Avoid using Run Time Type Information (RTTI).
+ RTTI allows a
+programmer to query the C++ class of an object at run
+time. This is done by use of typeid or
+dynamic_cast.
Querying the type of an object at run-time frequently +means a design problem. Needing to know the type of an +object at runtime is often an indication that the design +of your class hierarchy is flawed.
+ +Undisciplined use of RTTI makes code hard to maintain. +It can lead to type-based decision trees or switch +statements scattered throughout the code, all of which +must be examined when making further changes.
+The standard alternatives to RTTI (described below) +require modification or redesign of the class hierarchy +in question. Sometimes such modifications are infeasible +or undesirable, particularly in widely-used or mature +code.
+ +RTTI can be useful in some unit tests. For example, it +is useful in tests of factory classes where the test has +to verify that a newly created object has the expected +dynamic type. It is also useful in managing the +relationship between objects and their mocks.
+ +RTTI is useful when considering multiple abstract +objects. Consider
+ +bool Base::Equal(Base* other) = 0;
+bool Derived::Equal(Base* other) {
+ Derived* that = dynamic_cast<Derived*>(other);
+ if (that == NULL)
+ return false;
+ ...
+}
+
+RTTI has legitimate uses but is prone to abuse, so you +must be careful when using it. You may use it freely in +unittests, but avoid it when possible in other code. In +particular, think twice before using RTTI in new code. If +you find yourself needing to write code that behaves +differently based on the class of an object, consider one +of the following alternatives to querying the type:
+ +-
+
- Virtual methods are the preferred way of executing + different code paths depending on a specific subclass + type. This puts the work within the object itself. + +
- If the work belongs outside the object and instead + in some processing code, consider a double-dispatch + solution, such as the Visitor design pattern. This + allows a facility outside the object itself to + determine the type of class using the built-in type + system. +
When the logic of a program guarantees that a given
+instance of a base class is in fact an instance of a
+particular derived class, then a
+dynamic_cast may be used freely on the
+object. Usually one
+can use a static_cast as an alternative in
+such situations.
Decision trees based on type are a strong indication +that your code is on the wrong track.
+ +if (typeid(*data) == typeid(D1)) {
+ ...
+} else if (typeid(*data) == typeid(D2)) {
+ ...
+} else if (typeid(*data) == typeid(D3)) {
+...
+
+
+Code such as this usually breaks when additional +subclasses are added to the class hierarchy. Moreover, +when properties of a subclass change, it is difficult to +find and modify all the affected code segments.
+ +Do not hand-implement an RTTI-like workaround. The +arguments against RTTI apply just as much to workarounds +like class hierarchies with type tags. Moreover, +workarounds disguise your true intent.
+Casting
+ +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
+cast formats like
+int y = (int)x or int y = int(x) (but the latter
+is okay when invoking a constructor of a class type).
C++ introduced a +different cast system from C that distinguishes the types +of cast operations.
+The problem with C casts is the ambiguity of the operation;
+sometimes you are doing a conversion
+(e.g., (int)3.5) and sometimes you are doing
+a cast (e.g., (int)"hello"). Brace
+initialization and C++ casts can often help avoid this
+ambiguity. Additionally, C++ casts are more visible when searching for
+them.
The C++-style cast syntax is verbose and cumbersome.
+Do not use C-style casts. Instead, use these C++-style casts when +explicit type conversion is necessary.
+ +-
+
- Use brace initialization to convert arithmetic types
+ (e.g.
int64{x}). This is the safest approach because code + will not compile if conversion can result in information loss. The + syntax is also concise.
+
+
+
+ - Use
static_castas the equivalent of a C-style cast + that does value conversion, when you need to + explicitly up-cast a pointer from a class to its superclass, or when + you need to explicitly cast a pointer from a superclass to a + subclass. In this last case, you must be sure your object is + actually an instance of the subclass.
+
+
+
+ - Use
const_castto remove the +constqualifier (see const).
+
+ - Use
reinterpret_castto do unsafe + conversions of pointer types to and from integer and + other pointer types. Use this only if you know what you + are doing and you understand the aliasing issues. +
+
+
+
See the
+RTTI section for guidance on the use of
+dynamic_cast.
Streams
+ +Use streams where appropriate, and stick to "simple" +usages.
+Streams are the standard I/O abstraction in C++, as
+exemplified by the standard header <iostream>.
+They are widely used in Google code, but only for debug logging
+and test diagnostics.
The << and >>
+stream operators provide an API for formatted I/O that
+is easily learned, portable, reusable, and extensible.
+printf, by contrast, doesn't even support
+string, to say nothing of user-defined types,
+and is very difficult to use portably.
+printf also obliges you to choose among the
+numerous slightly different versions of that function,
+and navigate the dozens of conversion specifiers.
Streams provide first-class support for console I/O
+via std::cin, std::cout,
+std::cerr, and std::clog.
+The C APIs do as well, but are hampered by the need to
+manually buffer the input.
-
+
- Stream formatting can be configured by mutating the +state of the stream. Such mutations are persistent, so +the behavior of your code can be affected by the entire +previous history of the stream, unless you go out of your +way to restore it to a known state every time other code +might have touched it. User code can not only modify the +built-in state, it can add new state variables and behaviors +through a registration system. + +
- It is difficult to precisely control stream output, due +to the above issues, the way code and data are mixed in +streaming code, and the use of operator overloading (which +may select a different overload than you expect). + +
- The practice of building up output through chains
+of
<<operators interferes with +internationalization, because it bakes word order into the +code, and streams' support for localization is +flawed.
+
+
+
+
+
+ - The streams API is subtle and complex, so programmers must +develop experience with it in order to use it effectively. +However, streams were historically banned in Google code (except +for logging and diagnostics), so Google engineers tend not to +have that experience. Consequently, streams-based code is likely +to be less readable and maintainable by Googlers than code based +on more familiar abstractions. + +
- Resolving the many overloads of
<<is +extremely costly for the compiler. When used pervasively in a +large code base, it can consume as much as 20% of the parsing +and semantic analysis time.
+
Use streams only when they are the best tool for the job. +This is typically the case when the I/O is ad-hoc, local, +human-readable, and targeted at other developers rather than +end-users. Be consistent with the code around you, and with the +codebase as a whole; if there's an established tool for +your problem, use that tool instead.
+ +Avoid using streams for I/O that faces external users or +handles untrusted data. Instead, find and use the appropriate +templating libraries to handle issues like internationalization, +localization, and security hardening.
+ +If you do use streams, avoid the stateful parts of the
+streams API (other than error state), such as imbue(),
+xalloc(), and register_callback().
+Use explicit formatting functions rather than
+stream manipulators or formatting flags to control formatting
+details such as number base, precision, or padding.
Overload << as a streaming operator
+for your type only if your type represents a value, and
+<< writes out a human-readable string
+representation of that value. Avoid exposing implementation
+details in the output of <<; if you need to print
+object internals for debugging, use named functions instead
+(a method named DebugString() is the most common
+convention).
Preincrement and Predecrement
+ +Use prefix form (++i) of the increment and
+decrement operators with iterators and other template
+objects.
When a variable
+is incremented (++i or i++) or
+decremented (--i or i--) and
+the value of the expression is not used, one must decide
+whether to preincrement (decrement) or postincrement
+(decrement).
When the return value is ignored, the "pre" form
+(++i) is never less efficient than the
+"post" form (i++), and is often more
+efficient. This is because post-increment (or decrement)
+requires a copy of i to be made, which is
+the value of the expression. If i is an
+iterator or other non-scalar type, copying i
+could be expensive. Since the two types of increment
+behave the same when the value is ignored, why not just
+always pre-increment?
The tradition developed, in C, of using post-increment
+when the expression value is not used, especially in
+for loops. Some find post-increment easier
+to read, since the "subject" (i) precedes
+the "verb" (++), just like in English.
For simple scalar +(non-object) values there is no reason to prefer one form +and we allow either. For iterators and other template +types, use pre-increment.
+Use of const
+ +Use const whenever it makes sense. With C++11,
+constexpr is a better choice for some uses of
+const.
Declared variables and parameters can be preceded
+by the keyword const to indicate the variables
+are not changed (e.g., const int foo). Class
+functions can have the const qualifier to
+indicate the function does not change the state of the
+class member variables (e.g., class Foo { int
+Bar(char c) const; };).
Easier for people to understand how variables are being +used. Allows the compiler to do better type checking, +and, conceivably, generate better code. Helps people +convince themselves of program correctness because they +know the functions they call are limited in how they can +modify your variables. Helps people know what functions +are safe to use without locks in multi-threaded +programs.
+const is viral: if you pass a
+const variable to a function, that function
+must have const in its prototype (or the
+variable will need a const_cast). This can
+be a particular problem when calling library
+functions.
const variables, data members, methods
+and arguments add a level of compile-time type checking;
+it is better to detect errors as soon as possible.
+Therefore we strongly recommend that you use
+const whenever it makes sense to do so:
-
+
- If a function guarantees that it will not modify an argument
+ passed by reference or by pointer, the corresponding function parameter
+ should be a reference-to-const (
const T&) or + pointer-to-const (const T*), respectively.
+
+ - Declare methods to be
constwhenever + possible. Accessors should almost always be +const. Other methods should be const if + they do not modify any data members, do not call any + non-constmethods, and do not return a + non-constpointer or + non-constreference to a data member.
+
+ - Consider making data members
const+ whenever they do not need to be modified after + construction.
+
The mutable keyword is allowed but is
+unsafe when used with threads, so thread safety should be
+carefully considered first.
Where to put the const
+ +Some people favor the form int const *foo
+to const int* foo. They argue that this is
+more readable because it's more consistent: it keeps the
+rule that const always follows the object
+it's describing. However, this consistency argument
+doesn't apply in codebases with few deeply-nested pointer
+expressions since most const expressions
+have only one const, and it applies to the
+underlying value. In such cases, there's no consistency
+to maintain. Putting the const first is
+arguably more readable, since it follows English in
+putting the "adjective" (const) before the
+"noun" (int).
That said, while we encourage putting
+const first, we do not require it. But be
+consistent with the code around you!
Use of constexpr
+ +In C++11, use constexpr to define true
+constants or to ensure constant initialization.
Some variables can be declared constexpr
+to indicate the variables are true constants, i.e. fixed at
+compilation/link time. Some functions and constructors
+can be declared constexpr which enables them
+to be used in defining a constexpr
+variable.
Use of constexpr enables definition of
+constants with floating-point expressions rather than
+just literals; definition of constants of user-defined
+types; and definition of constants with function
+calls.
Prematurely marking something as constexpr may cause +migration problems if later on it has to be downgraded. +Current restrictions on what is allowed in constexpr +functions and constructors may invite obscure workarounds +in these definitions.
+constexpr definitions enable a more
+robust specification of the constant parts of an
+interface. Use constexpr to specify true
+constants and the functions that support their
+definitions. Avoid complexifying function definitions to
+enable their use with constexpr. Do not use
+constexpr to force inlining.
Integer Types
+ +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
+<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.
+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,
+choose a larger type.
C++ does not specify the sizes of its integer types.
+Typically people assume that short is 16 bits,
+int is 32 bits, long is 32 bits
+and long long is 64 bits.
Uniformity of declaration.
+The sizes of integral types in C++ can vary based on +compiler and architecture.
+
+<stdint.h> 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
+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.
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
+particular, do not use unsigned types to say a number
+will never be negative. Instead, use
+assertions for this.
If your code is a container that returns a size, be +sure to use a type that will accommodate any possible +usage of your container. When in doubt, use a larger type +rather than a smaller type.
+ +Use care when converting integer types. Integer +conversions and promotions can cause non-intuitive +behavior.
+On Unsigned Integers
+ +Some people, including some textbook authors, +recommend using unsigned types to represent numbers that +are never negative. This is intended as a form of +self-documentation. However, in C, the advantages of such +documentation are outweighed by the real bugs it can +introduce. Consider:
+ +for (unsigned int i = foo.Length()-1; i >= 0; --i) ... ++ +
This code will never terminate! Sometimes gcc will +notice this bug and warn you, but often it will not. +Equally bad bugs can occur when comparing signed and +unsigned variables. Basically, C's type-promotion scheme +causes unsigned types to behave differently than one +might expect.
+ +So, document that a variable is non-negative using +assertions. Don't use an unsigned +type.
+64-bit Portability
+ +Code should be 64-bit and 32-bit friendly. Bear in mind +problems of printing, comparisons, and structure alignment.
+-
+
-
+
+ +printf()specifiers for some types + are not cleanly portable between 32-bit and 64-bit + systems. C99 defines some portable format specifiers. + Unfortunately, MSVC 7.1 does not understand some of + these specifiers and the standard is missing a few, + so we + have to define our own ugly versions in some cases + (in the style of the standard include file +inttypes.h):++ +// printf macros for size_t, in the style of inttypes.h +#ifdef _LP64 +#define __PRIS_PREFIX "z" +#else +#define __PRIS_PREFIX +#endif + +// Use these macros after a % in a printf format string +// to get correct 32/64 bit behavior, like this: +// size_t size = records.size(); +// printf("%" PRIuS "\n", size); + +#define PRIdS __PRIS_PREFIX "d" +#define PRIxS __PRIS_PREFIX "x" +#define PRIuS __PRIS_PREFIX "u" +#define PRIXS __PRIS_PREFIX "X" +#define PRIoS __PRIS_PREFIX "o" +++
+ ++ + +Type +DO NOT use +DO use +Notes ++ + + + +void *(or any pointer)%lx%p+ + + + + +int64_t%qd,%lld%" PRId64 "+ + + + + +uint64_t%qu,%llu, +%llx%" PRIu64 ", +%" PRIx64 "+ + + +size_t%u%" PRIuS ",%" PRIxS "+ C99 specifies +%zu+ + + +ptrdiff_t%d%" PRIdS "+ C99 specifies +%tdNote that the
+ + +PRI*macros expand to + independent strings which are concatenated by the + compiler. Hence if you are using a non-constant + format string, you need to insert the value of the + macro into the format, rather than the name. Note also + that spaces are required around the macro identifier to + separate it from the string literal. It is + still possible, as usual, to include length + specifiers, etc., after the%when using + thePRI*macros. So, e.g. +printf("x = %30" PRIuS "\n", x)would + expand on 32-bit Linux toprintf("x = %30" "u" + "\n", x), which the compiler will treat as +printf("x = %30u\n", x).
+
+ - Remember that
sizeof(void *)!= +sizeof(int). Useintptr_tif + you want a pointer-sized integer.
+
+ - 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+ 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 + to ensure that they are packed the same on both + architectures. + Most compilers offer a way to + alter structure alignment. For gcc, you can use +__attribute__((packed)). MSVC offers +#pragma pack()and +__declspec(align()).
+
+ -
+
Use the
+ + +LLorULL+ suffixes as needed to create 64-bit constants. For + example:int64_t my_value = 0x123456789LL; +uint64_t my_mask = 3ULL << 48; +
+
+
Preprocessor Macros
+ +Avoid defining macros, especially in headers; prefer
+inline functions, enums, and const variables.
+Name macros with a project-specific prefix. Do not use
+macros to define pieces of a C++ API.
Macros mean that the code you see is not the same as +the code the compiler sees. This can introduce unexpected +behavior, especially since macros have global scope.
+ +The problems introduced by macros are especially severe +when they are used to define pieces of a C++ API, +and still more so for public APIs. Every error message from +the compiler when developers incorrectly use that interface +now must explain how the macros formed the interface. +Refactoring and analysis tools have a dramatically harder +time updating the interface. As a consequence, we +specifically disallow using macros in this way. +For example, avoid patterns like:
+ +class WOMBAT_TYPE(Foo) {
+ // ...
+
+ public:
+ EXPAND_PUBLIC_WOMBAT_API(Foo)
+
+ EXPAND_WOMBAT_COMPARISONS(Foo, ==, <)
+};
+
+
+Luckily, macros are not nearly as necessary in C++ as
+they are in C. Instead of using a macro to inline
+performance-critical code, use an inline function.
+Instead of using a macro to store a constant, use a
+const variable. Instead of using a macro to
+"abbreviate" a long variable name, use a reference.
+Instead of using a macro to conditionally compile code
+... well, don't do that at all (except, of course, for
+the #define guards to prevent double
+inclusion of header files). It makes testing much more
+difficult.
Macros can do things these other techniques cannot, +and you do see them in the codebase, especially in the +lower-level libraries. And some of their special features +(like stringifying, concatenation, and so forth) are not +available through the language proper. But before using a +macro, consider carefully whether there's a non-macro way +to achieve the same result. If you need to use a macro to +define an interface, contact +your project leads to request +a waiver of this rule.
+ +The following usage pattern will avoid many problems +with macros; if you use macros, follow it whenever +possible:
+ +-
+
- Don't define macros in a
.hfile.
+
+ #definemacros right before you use + them, and#undefthem right after.
+
+ - Do not just
#undefan existing macro + before replacing it with your own; instead, pick a name + that's likely to be unique.
+
+ - Try not to use macros that expand to unbalanced C++ + constructs, or at least document that behavior + well. + +
- Prefer not using
##to generate + function/class/variable names.
+
Exporting macros from headers (i.e. defining them in a header
+without #undefing them before the end of the header)
+is extremely strongly discouraged. If you do export a macro from a
+header, it must have a globally unique name. To achieve this, it
+must be named with a prefix consisting of your project's namespace
+name (but upper case).
0 and nullptr/NULL
+ +Use 0 for integers, 0.0 for
+reals, nullptr (or NULL) for
+pointers, and '\0' for chars.
Use 0 for integers and 0.0
+for reals. This is not controversial.
For
+pointers (address values), there is a choice between
+0, NULL, and
+nullptr. For projects that allow C++11
+features, use nullptr. For C++03 projects,
+we prefer NULL because it looks like a
+pointer. In fact, some C++ compilers provide special
+definitions of NULL which enable them to
+give useful warnings, particularly in situations where
+sizeof(NULL) is not equal to
+sizeof(0).
Use '\0' for chars. This is the correct
+type and also makes code more readable.
sizeof
+ +Prefer sizeof(varname) to
+sizeof(type).
Use sizeof(varname) when you
+take the size of a particular variable.
+sizeof(varname) will update
+appropriately if someone changes the variable type either
+now or later. You may use
+sizeof(type) for code unrelated
+to any particular variable, such as code that manages an
+external or internal data format where a variable of an
+appropriate C++ type is not convenient.
Struct data; +memset(&data, 0, sizeof(data)); ++ +
memset(&data, 0, sizeof(Struct)); ++ +
if (raw_size < sizeof(int)) {
+ LOG(ERROR) << "compressed record not big enough for count: " << raw_size;
+ return false;
+}
+
+
+auto
+ +Use auto to avoid type names that are noisy, obvious,
+or unimportant - cases where the type doesn't aid in clarity for the
+reader. Continue to use manifest type declarations when it helps
+readability.
+
-
+
- C++ type names can be long and cumbersome, especially when they +involve templates or namespaces. +
- When a C++ type name is repeated within a single declaration or a +small code region, the repetition may not be aiding readability. +
- It is sometimes safer to let the type be specified by the type of +the initialization expression, since that avoids the possibility of +unintended copies or type conversions. +
Sometimes code is clearer when types are manifest, +especially when a variable's initialization depends on +things that were declared far away. In expressions +like:
+ +auto foo = x.add_foo(); +auto i = y.Find(key); ++ +
it may not be obvious what the resulting types are if the type
+of y isn't very well known, or if y was
+declared many lines earlier.
Programmers have to understand the difference between
+auto and const auto& or
+they'll get copies when they didn't mean to.
If an auto variable is used as part of an
+interface, e.g. as a constant in a header, then a
+programmer might change its type while only intending to
+change its value, leading to a more radical API change
+than intended.
auto is permitted when it increases readability,
+particularly as described below. Never initialize an auto-typed
+variable with a braced initializer list.
Specific cases where auto is allowed or encouraged:
+
-
+
- (Encouraged) For iterators and other long/cluttery type names, particularly
+when the type is clear from context (calls
+to
find,begin, orendfor +instance).
+ - (Allowed) When the type is clear from local context (in the same expression
+or within a few lines). Initialization of a pointer or smart pointer
+with calls
+to
new+commonly falls into this category, as does use ofautoin +a range-based loop over a container whose type is spelled out +nearby.
+ - (Allowed) When the type doesn't matter because it isn't being used for +anything other than equality comparison. +
- (Encouraged) When iterating over a map with a range-based loop
+(because it is often assumed that the correct type
+is
std::pair<KeyType, ValueType>whereas it is actually +std::pair<const KeyType, ValueType>). This is +particularly well paired with localkey+andvaluealiases for.first+and.second(often const-ref). +for (const auto& item : some_map) { + const KeyType& key = item.first; + const ValType& value = item.second; + // The rest of the loop can now just refer to key and value, + // a reader can see the types in question, and we've avoided + // the too-common case of extra copies in this iteration. +} ++
+
Braced Initializer List
+ +You may use braced initializer lists.
+In C++03, aggregate types (arrays and structs with no +constructor) could be initialized with braced initializer lists.
+ +struct Point { int x; int y; };
+Point p = {1, 2};
+
+
+In C++11, this syntax was generalized, and any object type can now +be created with a braced initializer list, known as a +braced-init-list in the C++ grammar. Here are a few examples +of its use.
+ +// Vector takes a braced-init-list of elements.
+std::vector<string> v{"foo", "bar"};
+
+// Basically the same, ignoring some small technicalities.
+// You may choose to use either form.
+std::vector<string> v = {"foo", "bar"};
+
+// Usable with 'new' expressions.
+auto p = new vector<string>{"foo", "bar"};
+
+// A map can take a list of pairs. Nested braced-init-lists work.
+std::map<int, string> m = {{1, "one"}, {2, "2"}};
+
+// A braced-init-list can be implicitly converted to a return type.
+std::vector<int> test_function() { return {1, 2, 3}; }
+
+// Iterate over a braced-init-list.
+for (int i : {-1, -2, -3}) {}
+
+// Call a function using a braced-init-list.
+void TestFunction2(std::vector<int> v) {}
+TestFunction2({1, 2, 3});
+
+
+A user-defined type can also define a constructor and/or assignment operator
+that take std::initializer_list<T>, which is automatically
+created from braced-init-list:
class MyType {
+ public:
+ // std::initializer_list references the underlying init list.
+ // It should be passed by value.
+ MyType(std::initializer_list<int> init_list) {
+ for (int i : init_list) append(i);
+ }
+ MyType& operator=(std::initializer_list<int> init_list) {
+ clear();
+ for (int i : init_list) append(i);
+ }
+};
+MyType m{2, 3, 5, 7};
+
+
+Finally, brace initialization can also call ordinary
+constructors of data types, even if they do not have
+std::initializer_list<T> constructors.
double d{1.23};
+// Calls ordinary constructor as long as MyOtherType has no
+// std::initializer_list constructor.
+class MyOtherType {
+ public:
+ explicit MyOtherType(string);
+ MyOtherType(int, string);
+};
+MyOtherType m = {1, "b"};
+// If the constructor is explicit, you can't use the "= {}" form.
+MyOtherType m{"b"};
+
+
+Never assign a braced-init-list to an auto +local variable. In the single element case, what this +means can be confusing.
+ +auto d = {1.23}; // d is a std::initializer_list<double>
+
+
+auto d = double{1.23}; // Good -- d is a double, not a std::initializer_list.
+
+
+See Braced_Initializer_List_Format for formatting.
+ +Lambda expressions
+ +Use lambda expressions where appropriate. Prefer explicit captures +when the lambda will escape the current scope.
+Lambda expressions are a concise way of creating anonymous +function objects. They're often useful when passing +functions as arguments. For example:
+ +std::sort(v.begin(), v.end(), [](int x, int y) {
+ return Weight(x) < Weight(y);
+});
+
+
+They further allow capturing variables from the enclosing scope either +explicitly by name, or implicitly using a default capture. Explicit captures +require each variable to be listed, as +either a value or reference capture:
+ +int weight = 3;
+int sum = 0;
+// Captures `weight` by value and `sum` by reference.
+std::for_each(v.begin(), v.end(), [weight, &sum](int x) {
+ sum += weight * x;
+});
+
+
+
+Default captures implicitly capture any variable referenced in the
+lambda body, including this if any members are used:
+
+const std::vector<int> lookup_table = ...;
+std::vector<int> indices = ...;
+// Captures `lookup_table` by reference, sorts `indices` by the value
+// of the associated element in `lookup_table`.
+std::sort(indices.begin(), indices.end(), [&](int a, int b) {
+ return lookup_table[a] < lookup_table[b];
+});
+
+
+Lambdas were introduced in C++11 along with a set of utilities
+for working with function objects, such as the polymorphic
+wrapper std::function.
+
-
+
- Lambdas are much more concise than other ways of + defining function objects to be passed to STL + algorithms, which can be a readability + improvement. + +
- Appropriate use of default captures can remove + redundancy and highlight important exceptions from + the default. + +
- Lambdas,
std::function, and +std::bindcan be used in combination as a + general purpose callback mechanism; they make it easy + to write functions that take bound functions as + arguments.
+
-
+
- Variable capture in lambdas can be a source of dangling-pointer + bugs, particularly if a lambda escapes the current scope. + +
- Default captures by value can be misleading because they do not prevent + dangling-pointer bugs. Capturing a pointer by value doesn't cause a deep + copy, so it often has the same lifetime issues as capture by reference. + This is especially confusing when capturing 'this' by value, since the use + of 'this' is often implicit. + +
- It's possible for use of lambdas to get out of + hand; very long nested anonymous functions can make + code harder to understand. + +
-
+
- Use lambda expressions where appropriate, with formatting as +described below. +
- Prefer explicit captures if the lambda may escape the current scope.
+For example, instead of:
+
{ + Foo foo; + ... + executor->Schedule([&] { Frobnicate(foo); }) + ... +} +// BAD! The fact that the lambda makes use of a reference to `foo` and +// possibly `this` (if `Frobnicate` is a member function) may not be +// apparent on a cursory inspection. If the lambda is invoked after +// the function returns, that would be bad, because both `foo` +// and the enclosing object could have been destroyed. ++prefer to write: +{ + Foo foo; + ... + executor->Schedule([&foo] { Frobnicate(foo); }) + ... +} +// BETTER - The compile will fail if `Frobnicate` is a member +// function, and it's clearer that `foo` is dangerously captured by +// reference. ++
+ - Use default capture by reference ([&]) only when the +lifetime of the lambda is obviously shorter than any potential +captures. + +
- Use default capture by value ([=]) only as a means of binding a +few variables for a short lambda, where the set of captured +variables is obvious at a glance. Prefer not to write long or +complex lambdas with default capture by value. + +
- Keep unnamed lambdas short. If a lambda body is more than +maybe five lines long, prefer to give the lambda a name, or to +use a named function instead of a lambda. +
- Specify the return type of the lambda explicitly if that will
+make it more obvious to readers, as with
+
auto.
+
+
Template metaprogramming
+Avoid complicated template programming.
+Template metaprogramming refers to a family of techniques that +exploit the fact that the C++ template instantiation mechanism is +Turing complete and can be used to perform arbitrary compile-time +computation in the type domain.
+Template metaprogramming allows extremely flexible interfaces that
+are type safe and high performance. Facilities like
+
+Google Test,
+std::tuple, std::function, and
+Boost.Spirit would be impossible without it.
The techniques used in template metaprogramming are often obscure +to anyone but language experts. Code that uses templates in +complicated ways is often unreadable, and is hard to debug or +maintain.
+ +Template metaprogramming often leads to extremely poor compiler +time error messages: even if an interface is simple, the complicated +implementation details become visible when the user does something +wrong.
+ +Template metaprogramming interferes with large scale refactoring by +making the job of refactoring tools harder. First, the template code +is expanded in multiple contexts, and it's hard to verify that the +transformation makes sense in all of them. Second, some refactoring +tools work with an AST that only represents the structure of the code +after template expansion. It can be difficult to automatically work +back to the original source construct that needs to be +rewritten.
+Template metaprogramming sometimes allows cleaner and easier-to-use +interfaces than would be possible without it, but it's also often a +temptation to be overly clever. It's best used in a small number of +low level components where the extra maintenance burden is spread out +over a large number of uses.
+ +Think twice before using template metaprogramming or other
+complicated template techniques; think about whether the average
+member of your team will be able to understand your code well enough
+to maintain it after you switch to another project, or whether a
+non-C++ programmer or someone casually browsing the code base will be
+able to understand the error messages or trace the flow of a function
+they want to call. If you're using recursive template instantiations
+or type lists or metafunctions or expression templates, or relying on
+SFINAE or on the sizeof trick for detecting function
+overload resolution, then there's a good chance you've gone too
+far.
If you use template metaprogramming, you should expect to put +considerable effort into minimizing and isolating the complexity. You +should hide metaprogramming as an implementation detail whenever +possible, so that user-facing headers are readable, and you should +make sure that tricky code is especially well commented. You should +carefully document how the code is used, and you should say something +about what the "generated" code looks like. Pay extra attention to the +error messages that the compiler emits when users make mistakes. The +error messages are part of your user interface, and your code should +be tweaked as necessary so that the error messages are understandable +and actionable from a user point of view.
+ +Boost
+ +Use only approved libraries from the Boost library +collection.
+The + +Boost library collection is a popular collection of +peer-reviewed, free, open-source C++ libraries.
+Boost code is generally very high-quality, is widely +portable, and fills many important gaps in the C++ +standard library, such as type traits and better binders.
+Some Boost libraries encourage coding practices which can +hamper readability, such as metaprogramming and other +advanced template techniques, and an excessively +"functional" style of programming.
+In order to maintain a high level of readability for +all contributors who might read and maintain code, we +only allow an approved subset of Boost features. +Currently, the following libraries are permitted:
+ +-
+
-
+
+ Call Traits from
boost/call_traits.hpp
+
+ -
+ Compressed Pair from
boost/compressed_pair.hpp
+
+ -
+ The Boost Graph Library (BGL) from
boost/graph, + except serialization (adj_list_serialize.hpp) and + parallel/distributed algorithms and data structures + (boost/graph/parallel/*and +boost/graph/distributed/*).
+
+ -
+ Property Map from
boost/property_map, except + parallel/distributed property maps (boost/property_map/parallel/*).
+
+ -
+ Iterator from
boost/iterator
+
+ - The part of
+ Polygon that deals with Voronoi diagram
+ construction and doesn't depend on the rest of
+ Polygon:
+
boost/polygon/voronoi_builder.hpp, +boost/polygon/voronoi_diagram.hpp, and +boost/polygon/voronoi_geometry_type.hpp
+
+ -
+ Bimap from
boost/bimap
+
+ -
+ Statistical Distributions and Functions from
+
boost/math/distributions
+
+ -
+ Special Functions from
boost/math/special_functions
+
+ -
+ Multi-index from
boost/multi_index
+
+ -
+ Heap from
boost/heap
+
+ - The flat containers from
+ Container:
+
boost/container/flat_map, and +boost/container/flat_set
+
+ - Intrusive
+ from
boost/intrusive.
+
+ - The
+
boost/sortlibrary.
+
+ - Preprocessor
+ from
boost/preprocessor.
+
We are actively considering adding other Boost +features to the list, so this list may be expanded in +the future.
+The following libraries are permitted, but their use +is discouraged because they've been superseded by +standard libraries in C++11:
+ +-
+
-
+ Array from
boost/array.hpp: use + +std::arrayinstead.
+
+ -
+ Pointer Container from
boost/ptr_container: use containers of + +std::unique_ptrinstead.
+
std::hash
+ +Do not define specializations of std::hash.
std::hash<T> is the function object that the
+C++11 hash containers use to hash keys of type T,
+unless the user explicitly specifies a different hash function. For
+example, std::unordered_map<int, string> is a hash
+map that uses std::hash<int> to hash its keys,
+whereas std::unordered_map<int, string, MyIntHash>
+uses MyIntHash.
std::hash is defined for all integral, floating-point,
+pointer, and enum types, as well as some standard library
+types such as string and unique_ptr. Users
+can enable it to work for their own types by defining specializations
+of it for those types.
std::hash is easy to use, and simplifies the code
+since you don't have to name it explicitly. Specializing
+std::hash is the standard way of specifying how to
+hash a type, so it's what outside resources will teach, and what
+new engineers will expect.
std::hash is hard to specialize. It requires a lot
+of boilerplate code, and more importantly, it combines responsibility
+for identifying the hash inputs with responsibility for executing the
+hashing algorithm itself. The type author has to be responsible for
+the former, but the latter requires expertise that a type author
+usually doesn't have, and shouldn't need. The stakes here are high
+because low-quality hash functions can be security vulnerabilities,
+due to the emergence of
+
+hash flooding attacks.
Even for experts, std::hash specializations are
+inordinately difficult to implement correctly for compound types,
+because the implementation cannot recursively call std::hash
+on data members. High-quality hash algorithms maintain large
+amounts of internal state, and reducing that state to the
+size_t bytes that std::hash
+returns is usually the slowest part of the computation, so it
+should not be done more than once.
Due to exactly that issue, std::hash does not work
+with std::pair or std::tuple, and the
+language does not allow us to extend it to support them.
You can use std::hash with the types that it supports
+"out of the box", but do not specialize it to support additional types.
+If you need a hash table with a key type that std::hash
+does not support, consider using legacy hash containers (e.g.
+hash_map) for now; they use a different default hasher,
+which is unaffected by this prohibition.
If you want to use the standard hash containers anyway, you will +need to specify a custom hasher for the key type, e.g.
+std::unordered_map<MyKeyType, Value, MyKeyTypeHasher> my_map; +
+Consult with the type's owners to see if there is an existing hasher +that you can use; otherwise work with them to provide one, + or roll your own.
+ +We are planning to provide a hash function that can work with any type,
+using a new customization mechanism that doesn't have the drawbacks of
+std::hash.
C++11
+ +Use libraries and language extensions from C++11 when appropriate. +Consider portability to other environments +before using C++11 features in your +project.
+ +C++11 contains +significant changes both to the language and +libraries.
+C++11 was the official standard until august 2014, and +is supported by most C++ compilers. It standardizes +some common C++ extensions that we use already, allows +shorthands for some operations, and has some performance +and safety improvements.
+The C++11 standard is substantially more complex than +its predecessor (1,300 pages versus 800 pages), and is +unfamiliar 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, particularly in the case of projects that are +forced to use older versions of tools.
+ +As with Boost, some C++11 +extensions encourage coding practices that hamper +readability—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.
+ + +C++11 features may be used unless specified otherwise. +In addition to what's described in the rest of the style +guide, the following C++11 features may not be used:
+ +-
+
+
+
+
+
+
+
+
+
- Compile-time rational numbers
+ (
<ratio>), because of concerns that + it's tied to a more template-heavy interface + style.
+
+ - The
<cfenv>and +<fenv.h>headers, because many + compilers do not support those features reliably.
+
+ - Ref-qualifiers on member functions, such as
void X::Foo() + &orvoid X::Foo() &&, because of concerns + that they're an overly obscure feature.
+
+
+
+
+
Nonstandard Extensions
+ +Nonstandard extensions to C++ may not be used unless otherwise specified.
+Compilers support various extensions that are not part of standard C++. Such
+ extensions include GCC's __attribute__, intrinsic functions such
+ as __builtin_prefetch, designated initializers (e.g.
+ Foo f = {.field = 3}), inline assembly, __COUNTER__,
+ __PRETTY_FUNCTION__, compound statement expressions (e.g.
+ foo = ({ int x; Bar(&x); x }), variable-length arrays and
+ alloca(), and the a?:b syntax.
-
+
- Nonstandard extensions may provide useful features that do not exist + in standard C++. For example, some people think that designated + initializers are more readable than standard C++ features like + constructors. +
- Important performance guidance to the compiler can only be specified + using extensions. +
-
+
- Nonstandard extensions do not work in all compilers. Use of nonstandard + extensions reduces portability of code. +
- Even if they are supported in all targeted compilers, the extensions + are often not well-specified, and there may be subtle behavior differences + between compilers. +
- Nonstandard extensions add to the language features that a reader must + know to understand the code. +
Do not use nonstandard extensions. You may use portability wrappers that + are implemented using nonstandard extensions, so long as those wrappers + + are provided by a designated project-wide + portability header.
+Aliases
+ +Public aliases are for the benefit of an API's user, and should be clearly documented.
+There are several ways to create names that are aliases of other entities:
+typedef Foo Bar; +using Bar = Foo; +using other_namespace::Foo; ++ +
Like other declarations, aliases declared in a header file are part of that + header's public API unless they're in a function definition, in the private portion of a class, + or in an explicitly-marked internal namespace. Aliases in such areas or in .cc files are + implementation details (because client code can't refer to them), and are not restricted by this + rule.
+-
+
- Aliases can improve readability by simplifying a long or complicated name. +
- Aliases can reduce duplication by naming in one place a type used repeatedly in an API, + which might make it easier to change the type later. + +
-
+
- When placed in a header where client code can refer to them, aliases increase the + number of entities in that header's API, increasing its complexity. +
- Clients can easily rely on unintended details of public aliases, making + changes difficult. +
- It can be tempting to create a public alias that is only intended for use + in the implementation, without considering its impact on the API, or on maintainability. +
- Aliases can create risk of name collisions +
- Aliases can reduce readability by giving a familiar construct an unfamiliar name +
- Type aliases can create an unclear API contract: + it is unclear whether the alias is guaranteed to be identical to the type it aliases, + to have the same API, or only to be usable in specified narrow ways +
Don't put an alias in your public API just to save typing in the implementation; + do so only if you intend it to be used by your clients.
+When defining a public alias, document the intent of +the new name, including whether it is guaranteed to always be the same as the type +it's currently aliased to, or whether a more limited compatibility is +intended. This lets the user know whether they can treat the types as +substitutable or whether more specific rules must be followed, and can help the +implementation retain some degree of freedom to change the alias.
+Don't put namespace aliases in your public API. (See also Namespaces). +
+ +For example, these aliases document how they are intended to be used in client code:
+namespace a {
+// Used to store field measurements. DataPoint may change from Bar* to some internal type.
+// Client code should treat it as an opaque pointer.
+using DataPoint = foo::bar::Bar*;
+
+// A set of measurements. Just an alias for user convenience.
+using TimeSeries = std::unordered_set<DataPoint, std::hash<DataPoint>, DataPointComparator>;
+} // namespace a
+
+
+These aliases don't document intended use, and half of them aren't meant for client use:
+ +namespace a {
+// Bad: none of these say how they should be used.
+using DataPoint = foo::bar::Bar*;
+using std::unordered_set; // Bad: just for local convenience
+using std::hash; // Bad: just for local convenience
+typedef unordered_set<DataPoint, hash<DataPoint>, DataPointComparator> TimeSeries;
+} // namespace a
+
+
+However, local convenience aliases are fine in function definitions, private sections of + classes, explicitly marked internal namespaces, and in .cc files:
+ +// In a .cc file +using std::unordered_set; ++ +
Naming
+ +The most important consistency rules are those that govern +naming. The style of a name immediately informs us what sort of +thing the named entity is: a type, a variable, a function, a +constant, a macro, etc., without requiring us to search for the +declaration of that entity. The pattern-matching engine in our +brains relies a great deal on these naming rules. +
+ +Naming rules are pretty arbitrary, but + we feel that +consistency is more important than individual preferences in this +area, so regardless of whether you find them sensible or not, +the rules are the rules.
+ +General Naming Rules
+ +Names should be descriptive; avoid abbreviation.
+Give as descriptive a name as possible, within reason. +Do not worry about saving horizontal space as it is far +more important to make your code immediately +understandable by a new reader. Do not use abbreviations +that are ambiguous or unfamiliar to readers outside your +project, and do not abbreviate by deleting letters within +a word.
+ +int price_count_reader; // No abbreviation. +int num_errors; // "num" is a widespread convention. +int num_dns_connections; // Most people know what "DNS" stands for. ++ +
int n; // Meaningless. +int nerr; // Ambiguous abbreviation. +int n_comp_conns; // Ambiguous abbreviation. +int wgc_connections; // Only your group knows what this stands for. +int pc_reader; // Lots of things can be abbreviated "pc". +int cstmr_id; // Deletes internal letters. ++ +
Note that certain universally-known abbreviations are OK, such as
+i for an iteration variable and T for a
+template parameter.
Template parameters should follow the naming style for their +category: type template parameters should follow the rules for +type names, and non-type template +parameters should follow the rules for +variable names. + +
File Names
+ +Filenames should be all lowercase and can include
+underscores (_) or dashes (-).
+Follow the convention that your
+
+project uses. If there is no consistent
+local pattern to follow, prefer "_".
Examples of acceptable file names:
+ +-
+
my_useful_class.cc
+ my-useful-class.cc
+ myusefulclass.cc
+ myusefulclass_test.cc // _unittest and _regtest are deprecated.
+
C++ files should end in .cc and header files should end in
+.h. Files that rely on being textually included at specific points
+should end in .inc (see also the section on
+self-contained headers).
Do not use filenames that already exist in
+/usr/include, such as db.h.
In general, make your filenames very specific. For
+example, use http_server_logs.h rather than
+logs.h. A very common case is to have a pair
+of files called, e.g., foo_bar.h and
+foo_bar.cc, defining a class called
+FooBar.
Inline functions must be in a .h file. If
+your inline functions are very short, they should go
+directly into your .h file.
Type Names
+ +Type names start with a capital letter and have a capital
+letter for each new word, with no underscores:
+MyExcitingClass, MyExcitingEnum.
The names of all types — classes, structs, type aliases, +enums, and type template parameters — have the same naming convention. +Type names should start with a capital letter and have a capital letter +for each new word. No underscores. For example:
+ +// classes and structs
+class UrlTable { ...
+class UrlTableTester { ...
+struct UrlTableProperties { ...
+
+// typedefs
+typedef hash_map<UrlTableProperties *, string> PropertiesMap;
+
+// using aliases
+using PropertiesMap = hash_map<UrlTableProperties *, string>;
+
+// enums
+enum UrlTableErrors { ...
+
+
+Variable Names
+ +The names of variables (including function parameters) and data members are
+all lowercase, with underscores between words. Data members of classes (but not
+structs) additionally have trailing underscores. For instance:
+a_local_variable, a_struct_data_member,
+a_class_data_member_.
Common Variable names
+ +For example:
+ +string table_name; // OK - uses underscore. +string tablename; // OK - all lowercase. ++ +
string tableName; // Bad - mixed case. ++ +
Class Data Members
+ +Data members of classes, both static and non-static, are +named like ordinary nonmember variables, but with a +trailing underscore.
+ +class TableInfo {
+ ...
+ private:
+ string table_name_; // OK - underscore at end.
+ string tablename_; // OK.
+ static Pool<TableInfo>* pool_; // OK.
+};
+
+
+Struct Data Members
+ +Data members of structs, both static and non-static, +are named like ordinary nonmember variables. They do not have +the trailing underscores that data members in classes have.
+ +struct UrlTableProperties {
+ string name;
+ int num_entries;
+ static Pool<UrlTableProperties>* pool;
+};
+
+
+
+See Structs vs. +Classes for a discussion of when to use a struct +versus a class.
+ +Constant Names
+ +Variables declared constexpr or const, and whose value is fixed for + the duration of the program, are named with a leading "k" followed + by mixed case. For example:
+const int kDaysInAWeek = 7; ++ +
All such variables with static storage duration (i.e. statics and globals, + see + Storage Duration for details) should be named this way. This + convention is optional for variables of other storage classes, e.g. automatic + variables, otherwise the usual variable naming rules apply.
+ +
Function Names
+ +Regular functions have mixed case; accessors and mutators may be named +like variables.
+Ordinarily, functions should start with a capital letter and have a
+capital letter for each new word
+(a.k.a. "Camel
+Case" or "Pascal case"). Such names should not have
+underscores. Prefer to capitalize acronyms as single words
+(i.e. StartRpc(), not StartRPC()).
AddTableEntry() +DeleteUrl() +OpenFileOrDie() ++ +
(The same naming rule applies to class- and namespace-scope +constants that are exposed as part of an API and that are intended to look +like functions, because the fact that they're +objects rather than functions is an unimportant implementation detail.)
+ +Accessors and mutators (get and set functions) may be named like
+variables. These often correspond to actual member variables, but this is
+not required. For example, int count() and void
+set_count(int count).
Namespace Names
+ +The name of a top-level namespace should usually be the +name of the project or team whose code is contained in that +namespace. The code in that namespace should usually be in +a directory whose basename matches the namespace name (or +subdirectories thereof).
+ + + + + +Keep in mind that the rule +against abbreviated names applies to namespaces just as much +as variable names. Code inside the namespace seldom needs to +mention the namespace name, so there's usually no particular need +for abbreviation anyway.
+ +Avoid nested namespaces that match well-known top-level
+namespaces. Collisions between namespace names can lead to surprising
+build breaks because of name lookup rules. In particular, do not
+create any nested std namespaces. Prefer unique project
+identifiers
+(websearch::index, websearch::index_util)
+over collision-prone names like websearch::util.
For internal namespaces, be wary of other code being
+added to the same internal namespace causing a collision
+(internal helpers within a team tend to be related and may lead to
+collisions). In such a situation, using the filename to make a unique
+internal name is helpful
+(websearch::index::frobber_internal for use
+in frobber.h)
Enumerator Names
+ +Enumerators (for both scoped and unscoped enums) should be named either like
+constants or like
+macros: either kEnumName or
+ENUM_NAME.
Preferably, the individual enumerators should be named
+like constants. However, it
+is also acceptable to name them like
+macros. The enumeration name,
+UrlTableErrors (and
+AlternateUrlTableErrors), is a type, and
+therefore mixed case.
enum UrlTableErrors {
+ kOK = 0,
+ kErrorOutOfMemory,
+ kErrorMalformedInput,
+};
+enum AlternateUrlTableErrors {
+ OK = 0,
+ OUT_OF_MEMORY = 1,
+ MALFORMED_INPUT = 2,
+};
+
+
+Until January 2009, the style was to name enum values +like macros. This caused +problems with name collisions between enum values and +macros. Hence, the change to prefer constant-style naming +was put in place. New code should prefer constant-style +naming if possible. However, there is no reason to change +old code to use constant-style names, unless the old +names are actually causing a compile-time problem.
+ + + +Macro Names
+ +You're not really going to
+define a macro, are you? If you do, they're like this:
+MY_MACRO_THAT_SCARES_SMALL_CHILDREN.
Please see the description +of macros; in general macros should not be used. +However, if they are absolutely needed, then they should be +named with all capitals and underscores.
+ +#define ROUND(x) ... +#define PI_ROUNDED 3.0 ++ +
Exceptions to Naming Rules
+ +If you are naming something that is analogous to an +existing C or C++ entity then you can follow the existing +naming convention scheme.
+-
+
bigopen()
+ - function name, follows form of
open()
+
+ uint
+ typedef
+
+ bigpos
+ structorclass, follows + form ofpos
+
+ sparse_hash_map
+ - STL-like entity; follows STL naming conventions + +
LONGLONG_MAX
+ - a constant, as in
INT_MAX
+
Comments
+ +Though a pain to write, comments are absolutely vital to +keeping our code readable. The following rules describe what +you should comment and where. But remember: while comments are +very important, the best code is self-documenting. Giving +sensible names to types and variables is much better than using +obscure names that you must then explain through comments.
+ +When writing your comments, write for your audience: the +next +contributor who will need to +understand your code. Be generous — the next +one may be you!
+ +Comment Style
+ +Use either the // or /* */
+syntax, as long as you are consistent.
You can use either the // or the /*
+*/ syntax; however, // is
+much more common. Be consistent with how you
+comment and what style you use where.
File Comments
+ +Start each file with license boilerplate.
+ +File comments describe the contents of a file. If a file declares, +implements, or tests exactly one abstraction that is documented by a comment +at the point of declaration, file comments are not required. All other files +must have file comments.
+ +Legal Notice and Author +Line
+ + + +Every file should contain license +boilerplate. Choose the appropriate boilerplate for the +license used by the project (for example, Apache 2.0, +BSD, LGPL, GPL).
+ +If you make significant changes to a file with an +author line, consider deleting the author line.
+ +File Contents
+ +If a .h declares multiple abstractions, the file-level comment
+should broadly describe the contents of the file, and how the abstractions are
+related. A 1 or 2 sentence file-level comment may be sufficient. The detailed
+documentation about individual abstractions belongs with those abstractions,
+not at the file level.
Do not duplicate comments in both the .h and the
+.cc. Duplicated comments diverge.
Class Comments
+ +Every non-obvious class declaration should have an accompanying +comment that describes what it is for and how it should be used.
+// Iterates over the contents of a GargantuanTable.
+// Example:
+// GargantuanTableIterator* iter = table->NewIterator();
+// for (iter->Seek("foo"); !iter->done(); iter->Next()) {
+// process(iter->key(), iter->value());
+// }
+// delete iter;
+class GargantuanTableIterator {
+ ...
+};
+
+
+The class comment should provide the reader with enough information to know +how and when to use the class, as well as any additional considerations +necessary to correctly use the class. Document the synchronization assumptions +the class makes, if any. If an instance of the class can be accessed by +multiple threads, take extra care to document the rules and invariants +surrounding multithreaded use.
+ +The class comment is often a good place for a small example code snippet +demonstrating a simple and focused usage of the class.
+ +When sufficiently separated (e.g. .h and .cc
+files), comments describing the use of the class should go together with its
+interface definition; comments about the class operation and implementation
+should accompany the implementation of the class's methods.
Function Comments
+ +Declaration comments describe use of the function (when it is +non-obvious); comments at the definition of a function describe +operation.
+Function Declarations
+ +Almost every function declaration should have comments immediately +preceding it that describe what the function does and how to use +it. These comments may be omitted only if the function is simple and +obvious (e.g. simple accessors for obvious properties of the +class). These comments should be descriptive ("Opens the file") +rather than imperative ("Open the file"); the comment describes the +function, it does not tell the function what to do. In general, these +comments do not describe how the function performs its task. Instead, +that should be left to comments in the function definition.
+ +Types of things to mention in comments at the function +declaration:
+ +-
+
- What the inputs and outputs are. + +
- For class member functions: whether the object + remembers reference arguments beyond the duration of + the method call, and whether it will free them or + not. + +
- If the function allocates memory that the caller + must free. + +
- Whether any of the arguments can be a null + pointer. + +
- If there are any performance implications of how a + function is used. + +
- If the function is re-entrant. What are its + synchronization assumptions? +
Here is an example:
+ +// Returns an iterator for this table. It is the client's
+// responsibility to delete the iterator when it is done with it,
+// and it must not use the iterator once the GargantuanTable object
+// on which the iterator was created has been deleted.
+//
+// The iterator is initially positioned at the beginning of the table.
+//
+// This method is equivalent to:
+// Iterator* iter = table->NewIterator();
+// iter->Seek("");
+// return iter;
+// If you are going to immediately seek to another place in the
+// returned iterator, it will be faster to use NewIterator()
+// and avoid the extra seek.
+Iterator* GetIterator() const;
+
+
+However, do not be unnecessarily verbose or state the +completely obvious. Notice below that it is not necessary + to say "returns false otherwise" because this is +implied.
+ +// Returns true if the table cannot hold any more entries. +bool IsTableFull(); ++ +
When documenting function overrides, focus on the +specifics of the override itself, rather than repeating +the comment from the overridden function. In many of these +cases, the override needs no additional documentation and +thus no comment is required.
+ +When commenting constructors and destructors, remember +that the person reading your code knows what constructors +and destructors are for, so comments that just say +something like "destroys this object" are not useful. +Document what constructors do with their arguments (for +example, if they take ownership of pointers), and what +cleanup the destructor does. If this is trivial, just +skip the comment. It is quite common for destructors not +to have a header comment.
+ +Function Definitions
+ +If there is anything tricky about how a function does +its job, the function definition should have an +explanatory comment. For example, in the definition +comment you might describe any coding tricks you use, +give an overview of the steps you go through, or explain +why you chose to implement the function in the way you +did rather than using a viable alternative. For instance, +you might mention why it must acquire a lock for the +first half of the function but why it is not needed for +the second half.
+ +Note you should not just repeat the comments
+given with the function declaration, in the
+.h file or wherever. It's okay to
+recapitulate briefly what the function does, but the
+focus of the comments should be on how it does it.
Variable Comments
+ +In general the actual name of the variable should be +descriptive enough to give a good idea of what the variable +is used for. In certain cases, more comments are required.
+Class Data Members
+ +The purpose of each class data member (also called an instance
+variable or member variable) must be clear. If there are any
+invariants (special values, relationships between members, lifetime
+requirements) not clearly expressed by the type and name, they must be
+commented. However, if the type and name suffice (int
+num_events_;), no comment is needed.
In particular, add comments to describe the existence and meaning +of sentinel values, such as nullptr or -1, when they are not +obvious. For example:
+ +private: + // Used to bounds-check table accesses. -1 means + // that we don't yet know how many entries the table has. + int num_total_entries_; ++ +
Global Variables
+ +All global variables should have a comment describing what they +are, what they are used for, and (if unclear) why it needs to be +global. For example:
+ +// The total number of tests cases that we run through in this regression test. +const int kNumTestCases = 6; ++ +
Implementation Comments
+ +In your implementation you should have comments in tricky, +non-obvious, interesting, or important parts of your code.
+Explanatory Comments
+ +Tricky or complicated code blocks should have comments +before them. Example:
+ +// Divide result by two, taking into account that x
+// contains the carry from the add.
+for (int i = 0; i < result->size(); i++) {
+ x = (x << 8) + (*result)[i];
+ (*result)[i] = x >> 1;
+ x &= 1;
+}
+
+
+Line Comments
+ +Also, lines that are non-obvious should get a comment +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()); +if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) + return; // Error already logged. ++ +
Note that there are both comments that describe what +the code is doing, and comments that mention that an +error has already been logged when the function +returns.
+ +If you have several comments on subsequent lines, it +can often be more readable to line them up:
+ +DoSomething(); // Comment here so the comments line up.
+DoSomethingElseThatIsLonger(); // Two spaces between the code and the comment.
+{ // One space before comment when opening a new scope is allowed,
+ // thus the comment lines up with the following comments and code.
+ DoSomethingElse(); // Two spaces before line comments normally.
+}
+std::vector<string> list{
+ // Comments in braced lists describe the next element...
+ "First item",
+ // .. and should be aligned appropriately.
+ "Second item"};
+DoSomething(); /* For trailing block comments, one space is fine. */
+
+
+Function Argument Comments
+ +When the meaning of a function argument is nonobvious, consider +one of the following remedies:
+ +-
+
- If the argument is a literal constant, and the same constant is + used in multiple function calls in a way that tacitly assumes they're + the same, you should use a named constant to make that constraint + explicit, and to guarantee that it holds. + +
- Consider changing the function signature to replace a
bool+ argument with anenumargument. This will make the argument + values self-describing.
+
+ - For functions that have several configuration options, consider + defining a single class or struct to hold all the options + , + and pass an instance of that. + This approach has several advantages. Options are referenced by name + at the call site, which clarifies their meaning. It also reduces + function argument count, which makes function calls easier to read and + write. As an added benefit, you don't have to change call sites when + you add another option. + + +
- Replace large or complex nested expressions with named variables. + +
- As a last resort, use comments to clarify argument meanings at the + call site. +
// What are these arguments? +const DecimalNumber product = CalculateProduct(values, 7, false, nullptr); ++ +
versus:
+ +ProductOptions options; +options.set_precision_decimals(7); +options.set_use_cache(ProductOptions::kDontUseCache); +const DecimalNumber product = + CalculateProduct(values, options, /*completion_callback=*/nullptr); ++ +
Don'ts
+ +Do not state the obvious. In particular, don't literally describe what +code does, unless the behavior is nonobvious to a reader who understands +C++ well. Instead, provide higher level comments that describe why +the code does what it does, or make the code self describing.
+ +Compare this: + +// Find the element in the vector. <-- Bad: obvious!
+auto iter = std::find(v.begin(), v.end(), element);
+if (iter != v.end()) {
+ Process(element);
+}
+
+
+To this:
+
+// Process "element" unless it was already processed.
+auto iter = std::find(v.begin(), v.end(), element);
+if (iter != v.end()) {
+ Process(element);
+}
+
+
+Self-describing code doesn't need a comment. The comment from
+the example above would be obvious:
+
+if (!IsAlreadyProcessed(element)) {
+ Process(element);
+}
+
+
+Punctuation, Spelling and Grammar
+ +Pay attention to punctuation, spelling, and grammar; it is +easier to read well-written comments than badly written +ones.
+Comments should be as readable as narrative text, with +proper capitalization and punctuation. In many cases, +complete sentences are more readable than sentence +fragments. Shorter comments, such as comments at the end +of a line of code, can sometimes be less formal, but you +should be consistent with your style.
+ +Although it can be frustrating to have a code reviewer +point out that you are using a comma when you should be +using a semicolon, it is very important that source code +maintain a high level of clarity and readability. Proper +punctuation, spelling, and grammar help with that +goal.
+ +TODO Comments
+ +Use TODO comments for code that is temporary,
+a short-term solution, or good-enough but not perfect.
TODOs should include the string
+TODO in all caps, followed by the
+
+name, e-mail address, bug ID, or other
+identifier
+of the person or issue with the best context
+about the problem referenced by the TODO. The
+main purpose is to have a consistent TODO that
+can be searched to find out how to get more details upon
+request. A TODO is not a commitment that the
+person referenced will fix the problem. Thus when you create
+a TODO with a name, it is almost always your
+name that is given.
// TODO(kl@gmail.com): Use a "*" here for concatenation operator. +// TODO(Zeke) change this to use relations. +// TODO(bug 12345): remove the "Last visitors" feature ++
If your TODO is of the form "At a future
+date do something" make sure that you either include a
+very specific date ("Fix by November 2005") or a very
+specific event ("Remove this code when all clients can
+handle XML responses.").
Deprecation Comments
+ +Mark deprecated interface points with DEPRECATED
+comments.
You can mark an interface as deprecated by writing a
+comment containing the word DEPRECATED in
+all caps. The comment goes either before the declaration
+of the interface or on the same line as the
+declaration.
After the word
+DEPRECATED, write your name, e-mail address,
+or other identifier in parentheses.
A deprecation comment must include simple, clear +directions for people to fix their callsites. In C++, you +can implement a deprecated function as an inline function +that calls the new interface point.
+ +Marking an interface point DEPRECATED
+will not magically cause any callsites to change. If you
+want people to actually stop using the deprecated
+facility, you will have to fix the callsites yourself or
+recruit a crew to help you.
New code should not contain calls to deprecated +interface points. Use the new interface point instead. If +you cannot understand the directions, find the person who +created the deprecation and ask them for help using the +new interface point.
+ + + +Formatting
+ +Coding style and formatting are pretty arbitrary, but a + +project is much easier to follow +if everyone uses the same style. Individuals may not agree with every +aspect of the formatting rules, and some of the rules may take +some getting used to, but it is important that all + +project contributors follow the +style rules so that +they can all read and understand +everyone's code easily.
+ + + +To help you format code correctly, we've +created a + +settings file for emacs.
+ +Line Length
+ +Each line of text in your code should be at most 80 +characters long.
+We recognize that this rule is +controversial, but so much existing code already adheres +to it, and we feel that consistency is important.
+ +Those who favor this rule +argue that it is rude to force them to resize +their windows and there is no need for anything longer. +Some folks are used to having several code windows +side-by-side, and thus don't have room to widen their +windows in any case. People set up their work environment +assuming a particular maximum window width, and 80 +columns has been the traditional standard. Why change +it?
+Proponents of change argue that a wider line can make +code more readable. The 80-column limit is an hidebound +throwback to 1960s mainframes; modern equipment has wide screens that +can easily show longer lines.
+80 characters is the maximum.
+ +Comment lines can be longer than 80 +characters if it is not feasible to split them without +harming readability, ease of cut and paste or auto-linking +-- e.g. if a line contains an example command or a literal +URL longer than 80 characters.
+ +A raw-string literal may have content +that exceeds 80 characters. Except for test code, such literals +should appear near the top of a file.
+ +An #include statement with a
+long path may exceed 80 columns.
You needn't be concerned about +header guards that exceed +the maximum length.
+Non-ASCII Characters
+ +Non-ASCII characters should be rare, and must use UTF-8 +formatting.
+You shouldn't hard-code user-facing text in source, +even English, so use of non-ASCII characters should be +rare. However, in certain cases it is appropriate to +include such words in your code. For example, if your +code parses data files from foreign sources, it may be +appropriate to hard-code the non-ASCII string(s) used in +those data files as delimiters. More commonly, unittest +code (which does not need to be localized) might +contain non-ASCII strings. In such cases, you should use +UTF-8, since that is an encoding +understood by most tools able to handle more than just +ASCII.
+ +Hex encoding is also OK, and encouraged where it
+enhances readability — for example,
+"\xEF\xBB\xBF", or, even more simply,
+u8"\uFEFF", is the Unicode zero-width
+no-break space character, which would be invisible if
+included in the source as straight UTF-8.
Use the u8 prefix
+to guarantee that a string literal containing
+\uXXXX escape sequences is encoded as UTF-8.
+Do not use it for strings containing non-ASCII characters
+encoded as UTF-8, because that will produce incorrect
+output if the compiler does not interpret the source file
+as UTF-8.
You shouldn't use the C++11 char16_t and
+char32_t character types, since they're for
+non-UTF-8 text. For similar reasons you also shouldn't
+use wchar_t (unless you're writing code that
+interacts with the Windows API, which uses
+wchar_t extensively).
Spaces vs. Tabs
+ +Use only spaces, and indent 2 spaces at a time.
+We use spaces for indentation. Do not use tabs in your +code. You should set your editor to emit spaces when you +hit the tab key.
+ +Function Declarations and Definitions
+ +Return type on the same line as function name, parameters +on the same line if they fit. Wrap parameter lists which do +not fit on a single line as you would wrap arguments in a +function call.
+Functions look like this:
+ + +ReturnType ClassName::FunctionName(Type par_name1, Type par_name2) {
+ DoSomething();
+ ...
+}
+
+
+If you have too much text to fit on one line:
+ +ReturnType ClassName::ReallyLongFunctionName(Type par_name1, Type par_name2,
+ Type par_name3) {
+ DoSomething();
+ ...
+}
+
+
+or if you cannot fit even the first parameter:
+ +ReturnType LongClassName::ReallyReallyReallyLongFunctionName(
+ Type par_name1, // 4 space indent
+ Type par_name2,
+ Type par_name3) {
+ DoSomething(); // 2 space indent
+ ...
+}
+
+
+Some points to note:
+ +-
+
- Choose good parameter names. + +
- Parameter names may be omitted only if the parameter is unused and its + purpose is obvious. + +
- If you cannot fit the return type and the function + name on a single line, break between them. + +
- If you break after the return type of a function + declaration or definition, do not indent. + +
- The open parenthesis is always on the same line as + the function name. + +
- There is never a space between the function name + and the open parenthesis. + +
- There is never a space between the parentheses and + the parameters. + +
- The open curly brace is always on the end of the last line of the function + declaration, not the start of the next line. + +
- The close curly brace is either on the last line by + itself or on the same line as the open curly brace. + +
- There should be a space between the close + parenthesis and the open curly brace. + +
- All parameters should be aligned if possible. + +
- Default indentation is 2 spaces. + +
- Wrapped parameters have a 4 space indent. +
Unused parameters that are obvious from context may be omitted:
+ +class Foo {
+ public:
+ Foo(Foo&&);
+ Foo(const Foo&);
+ Foo& operator=(Foo&&);
+ Foo& operator=(const Foo&);
+};
+
+
+Unused parameters that might not be obvious should comment out the variable +name in the function definition:
+ +class Shape {
+ public:
+ virtual void Rotate(double radians) = 0;
+};
+
+class Circle : public Shape {
+ public:
+ void Rotate(double radians) override;
+};
+
+void Circle::Rotate(double /*radians*/) {}
+
+
+// Bad - if someone wants to implement later, it's not clear what the
+// variable means.
+void Circle::Rotate(double) {}
+
+
+Attributes, and macros that expand to attributes, appear at the very +beginning of the function declaration or definition, before the +return type:
+MUST_USE_RESULT bool IsOK(); ++ +
Lambda Expressions
+ +Format parameters and bodies as for any other function, and capture +lists like other comma-separated lists.
+For by-reference captures, do not leave a space between the +ampersand (&) and the variable name.
+int x = 0;
+auto x_plus_n = [&x](int n) -> int { return x + n; }
+
+Short lambdas may be written inline as function arguments.
+std::set<int> blacklist = {7, 8, 9};
+std::vector<int> digits = {3, 9, 1, 8, 4, 7, 1};
+digits.erase(std::remove_if(digits.begin(), digits.end(), [&blacklist](int i) {
+ return blacklist.find(i) != blacklist.end();
+ }),
+ digits.end());
+
+
+Function Calls
+ +Either write the call all on a single line, wrap the +arguments at the parenthesis, or start the arguments on a new +line indented by four spaces and continue at that 4 space +indent. In the absence of other considerations, use the +minimum number of lines, including placing multiple arguments +on each line where appropriate.
+Function calls have the following format:
+bool result = DoSomething(argument1, argument2, argument3); ++ +
If the arguments do not all fit on one line, they +should be broken up onto multiple lines, with each +subsequent line aligned with the first argument. Do not +add spaces after the open paren or before the close +paren:
+bool result = DoSomething(averyveryveryverylongargument1, + argument2, argument3); ++ +
Arguments may optionally all be placed on subsequent +lines with a four space indent:
+if (...) {
+ ...
+ ...
+ if (...) {
+ bool result = DoSomething(
+ argument1, argument2, // 4 space indent
+ argument3, argument4);
+ ...
+ }
+
+
+Put multiple arguments on a single line to reduce the +number of lines necessary for calling a function unless +there is a specific readability problem. Some find that +formatting with strictly one argument on each line is +more readable and simplifies editing of the arguments. +However, we prioritize for the reader over the ease of +editing arguments, and most readability problems are +better addressed with the following techniques.
+ +If having multiple arguments in a single line decreases +readability due to the complexity or confusing nature of the +expressions that make up some arguments, try creating +variables that capture those arguments in a descriptive name:
+int my_heuristic = scores[x] * y + bases[x]; +bool result = DoSomething(my_heuristic, x, y, z); ++ +
Or put the confusing argument on its own line with +an explanatory comment:
+bool result = DoSomething(scores[x] * y + bases[x], // Score heuristic. + x, y, z); ++ +
If there is still a case where one argument is +significantly more readable on its own line, then put it on +its own line. The decision should be specific to the argument +which is made more readable rather than a general policy.
+ +Sometimes arguments form a structure that is important +for readability. In those cases, feel free to format the +arguments according to that structure:
+// Transform the widget by a 3x3 matrix. +my_widget.Transform(x1, x2, x3, + y1, y2, y3, + z1, z2, z3); ++ +
Braced Initializer List Format
+ +Format a braced initializer list +exactly like you would format a function call in its place.
+If the braced list follows a name (e.g. a type or
+variable name), format as if the {} were the
+parentheses of a function call with that name. If there
+is no name, assume a zero-length name.
// Examples of braced init list on a single line.
+return {foo, bar};
+functioncall({foo, bar});
+std::pair<int, int> p{foo, bar};
+
+// When you have to wrap.
+SomeFunction(
+ {"assume a zero-length name before {"},
+ some_other_function_parameter);
+SomeType variable{
+ some, other, values,
+ {"assume a zero-length name before {"},
+ SomeOtherType{
+ "Very long string requiring the surrounding breaks.",
+ some, other values},
+ SomeOtherType{"Slightly shorter string",
+ some, other, values}};
+SomeType variable{
+ "This is too long to fit all in one line"};
+MyType m = { // Here, you could also break before {.
+ superlongvariablename1,
+ superlongvariablename2,
+ {short, interior, list},
+ {interiorwrappinglist,
+ interiorwrappinglist2}};
+
+
+Conditionals
+ +Prefer no spaces inside parentheses. The if
+and else keywords belong on separate lines.
There are two acceptable formats for a basic +conditional statement. One includes spaces between the +parentheses and the condition, and one does not.
+ +The most common form is without spaces. Either is +fine, but be consistent. If you are modifying a +file, use the format that is already present. If you are +writing new code, use the format that the other files in +that directory or project use. If in doubt and you have +no personal preference, do not add the spaces.
+ +if (condition) { // no spaces inside parentheses
+ ... // 2 space indent.
+} else if (...) { // The else goes on the same line as the closing brace.
+ ...
+} else {
+ ...
+}
+
+
+If you prefer you may add spaces inside the +parentheses:
+ +if ( condition ) { // spaces inside parentheses - rare
+ ... // 2 space indent.
+} else { // The else goes on the same line as the closing brace.
+ ...
+}
+
+
+Note that in all cases you must have a space between
+the if and the open parenthesis. You must
+also have a space between the close parenthesis and the
+curly brace, if you're using one.
if(condition) { // Bad - space missing after IF.
+if (condition){ // Bad - space missing before {.
+if(condition){ // Doubly bad.
+
+
+if (condition) { // Good - proper space after IF and before {.
+
+
+Short conditional statements may be written on one
+line if this enhances readability. You may use this only
+when the line is brief and the statement does not use the
+else clause.
if (x == kFoo) return new Foo(); +if (x == kBar) return new Bar(); ++ +
This is not allowed when the if statement has an
+else:
// Not allowed - IF statement on one line when there is an ELSE clause +if (x) DoThis(); +else DoThat(); ++ +
In general, curly braces are not required for
+single-line statements, but they are allowed if you like
+them; conditional or loop statements with complex
+conditions or statements may be more readable with curly
+braces. Some
+projects require that an
+if must always always have an accompanying
+brace.
if (condition)
+ DoSomething(); // 2 space indent.
+
+if (condition) {
+ DoSomething(); // 2 space indent.
+}
+
+
+However, if one part of an
+if-else statement uses curly
+braces, the other part must too:
// Not allowed - curly on IF but not ELSE
+if (condition) {
+ foo;
+} else
+ bar;
+
+// Not allowed - curly on ELSE but not IF
+if (condition)
+ foo;
+else {
+ bar;
+}
+
+
+// Curly braces around both IF and ELSE required because
+// one of the clauses used braces.
+if (condition) {
+ foo;
+} else {
+ bar;
+}
+
+
+Loops and Switch Statements
+ +Switch statements may use braces for blocks. Annotate
+non-trivial fall-through between cases.
+Braces are optional for single-statement loops.
+Empty loop bodies should use empty braces or continue.
case blocks in switch
+statements can have curly braces or not, depending on
+your preference. If you do include curly braces they
+should be placed as shown below.
If not conditional on an enumerated value, switch
+statements should always have a default case
+(in the case of an enumerated value, the compiler will
+warn you if any values are not handled). If the default
+case should never execute, simply
+assert:
switch (var) {
+ case 0: { // 2 space indent
+ ... // 4 space indent
+ break;
+ }
+ case 1: {
+ ...
+ break;
+ }
+ default: {
+ assert(false);
+ }
+}
+
+Braces are optional for single-statement loops.
+ +for (int i = 0; i < kSomeNumber; ++i)
+ printf("I love you\n");
+
+for (int i = 0; i < kSomeNumber; ++i) {
+ printf("I take it back\n");
+}
+
+
+
+Empty loop bodies should use an empty pair of braces or continue,
+but not a single semicolon.
while (condition) {
+ // Repeat test until it returns false.
+}
+for (int i = 0; i < kSomeNumber; ++i) {} // Good - one newline is also OK.
+while (condition) continue; // Good - continue indicates no logic.
+
+
+while (condition); // Bad - looks like part of do/while loop. ++ +
Pointer and Reference Expressions
+ +No spaces around period or arrow. Pointer operators do not +have trailing spaces.
+The following are examples of correctly-formatted +pointer and reference expressions:
+ +x = *p; +p = &x; +x = r.y; +x = r->y; ++ +
Note that:
+ +-
+
- There are no spaces around the period or arrow when + accessing a member. + +
- Pointer operators have no space after the
+
*or&.
+
When declaring a pointer variable or argument, you may +place the asterisk adjacent to either the type or to the +variable name:
+ +// These are fine, space preceding. +char *c; +const string &str; + +// These are fine, space following. +char* c; +const string& str; ++ +It is allowed (if unusual) to declare multiple variables in the same +declaration, but it is disallowed if any of those have pointer or +reference decorations. Such declarations are easily misread. +
// Fine if helpful for readability. +int x, y; ++
int x, *y; // Disallowed - no & or * in multiple declaration +char * c; // Bad - spaces on both sides of * +const string & str; // Bad - spaces on both sides of & ++ +
You should do this consistently within a single +file, +so, when modifying an existing file, use the style in +that file.
+ +Boolean Expressions
+ +When you have a boolean expression that is longer than the +standard line length, be +consistent in how you break up the lines.
+In this example, the logical AND operator is always at +the end of the lines:
+ +if (this_one_thing > this_other_thing &&
+ a_third_thing == a_fourth_thing &&
+ yet_another && last_one) {
+ ...
+}
+
+
+Note that when the code wraps in this example, both of
+the && logical AND operators are at
+the end of the line. This is more common in Google code,
+though wrapping all operators at the beginning of the
+line is also allowed. Feel free to insert extra
+parentheses judiciously because they can be very helpful
+in increasing readability when used
+appropriately. Also note that you should always use
+the punctuation operators, such as
+&& and ~, rather than
+the word operators, such as and and
+compl.
Return Values
+ +Do not needlessly surround the return
+expression with parentheses.
Use parentheses in return expr; only
+where you would use them in x = expr;.
return result; // No parentheses in the simple case. +// Parentheses OK to make a complex expression more readable. +return (some_long_condition && + another_condition); ++ +
return (value); // You wouldn't write var = (value); +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:
int x = 3;
+int x(3);
+int x{3};
+string name = "Some Name";
+string name("Some Name");
+string name{"Some Name"};
+
+
+Be careful when using a braced initialization list {...}
+on a type with an std::initializer_list constructor.
+A nonempty braced-init-list prefers the
+std::initializer_list constructor whenever
+possible. Note that empty braces {} are special, and
+will call a default constructor if available. To force the
+non-std::initializer_list constructor, use parentheses
+instead of braces.
std::vector<int> v(100, 1); // A vector of 100 1s.
+std::vector<int> v{100, 1}; // A vector of 100, 1.
+
+
+Also, the brace form prevents narrowing of integral +types. This can prevent some types of programming +errors.
+ +int pi(3.14); // OK -- pi == 3.
+int pi{3.14}; // Compile error: narrowing conversion.
+
+
+Preprocessor Directives
+ +The hash mark that starts a preprocessor directive should +always be at the beginning of the line.
+Even when preprocessor directives are within the body +of indented code, the directives should start at the +beginning of the line.
+ +// Good - directives at beginning of line
+ if (lopsided_score) {
+#if DISASTER_PENDING // Correct -- Starts at beginning of line
+ DropEverything();
+# if NOTIFY // OK but not required -- Spaces after #
+ NotifyClient();
+# endif
+#endif
+ BackToNormal();
+ }
+
+
+// Bad - indented directives
+ if (lopsided_score) {
+ #if DISASTER_PENDING // Wrong! The "#if" should be at beginning of line
+ DropEverything();
+ #endif // Wrong! Do not indent "#endif"
+ BackToNormal();
+ }
+
+
+Class Format
+ +Sections in public, protected and
+private order, each indented one space.
The basic format for a class definition (lacking the +comments, see Class +Comments for a discussion of what comments are +needed) is:
+ +class MyClass : public OtherClass {
+ public: // Note the 1 space indent!
+ MyClass(); // Regular 2 space indent.
+ explicit MyClass(int var);
+ ~MyClass() {}
+
+ void SomeFunction();
+ void SomeFunctionThatDoesNothing() {
+ }
+
+ void set_some_var(int var) { some_var_ = var; }
+ int some_var() const { return some_var_; }
+
+ private:
+ bool SomeInternalFunction();
+
+ int some_var_;
+ int some_other_var_;
+};
+
+
+Things to note:
+ +-
+
- Any base class name should be on the same line as + the subclass name, subject to the 80-column limit. + +
- The
public:,protected:, + andprivate:keywords should be indented + one space.
+
+ - Except for the first instance, these keywords + should be preceded by a blank line. This rule is + optional in small classes. + +
- Do not leave a blank line after these + keywords. + +
- The
publicsection should be first, + followed by theprotectedand finally the +privatesection.
+
+ - See Declaration + Order for rules on ordering declarations within + each of these sections. +
Constructor Initializer Lists
+ +Constructor initializer lists can be all on one line or +with subsequent lines indented four spaces.
+The acceptable formats for initializer lists are:
+ +// When everything fits on one line:
+MyClass::MyClass(int var) : some_var_(var) {
+ DoSomething();
+}
+
+// If the signature and initializer list are not all on one line,
+// you must wrap before the colon and indent 4 spaces:
+MyClass::MyClass(int var)
+ : some_var_(var), some_other_var_(var + 1) {
+ DoSomething();
+}
+
+// When the list spans multiple lines, put each member on its own line
+// and align them:
+MyClass::MyClass(int var)
+ : some_var_(var), // 4 space indent
+ some_other_var_(var + 1) { // lined up
+ DoSomething();
+}
+
+// As with any other code block, the close curly can be on the same
+// line as the open curly, if it fits.
+MyClass::MyClass(int var)
+ : some_var_(var) {}
+
+
+Namespace Formatting
+ +The contents of namespaces are not indented.
+Namespaces do not add an +extra level of indentation. For example, use:
+ +namespace {
+
+void foo() { // Correct. No extra indentation within namespace.
+ ...
+}
+
+} // namespace
+
+
+Do not indent within a namespace:
+ +namespace {
+
+ // Wrong. Indented when it should not be.
+ void foo() {
+ ...
+ }
+
+} // namespace
+
+
+When declaring nested namespaces, put each namespace +on its own line.
+ +namespace foo {
+namespace bar {
+
+
+Horizontal Whitespace
+ +Use of horizontal whitespace depends on location. Never put +trailing whitespace at the end of a line.
+General
+ +void f(bool b) { // Open braces should always have a space before them.
+ ...
+int i = 0; // Semicolons usually have no space before them.
+// Spaces inside braces for braced-init-list are optional. If you use them,
+// put them on both sides!
+int x[] = { 0 };
+int x[] = {0};
+
+// Spaces around the colon in inheritance and initializer lists.
+class Foo : public Bar {
+ public:
+ // For inline function implementations, put spaces between the braces
+ // and the implementation itself.
+ Foo(int b) : Bar(), baz_(b) {} // No spaces inside empty braces.
+ void Reset() { baz_ = 0; } // Spaces separating braces from implementation.
+ ...
+
+
+Adding trailing whitespace can cause extra work for +others editing the same file, when they merge, as can +removing existing trailing whitespace. So: Don't +introduce trailing whitespace. Remove it if you're +already changing that line, or do it in a separate +clean-up +operation (preferably when no-one +else is working on the file).
+ +Loops and Conditionals
+ +if (b) { // Space after the keyword in conditions and loops.
+} else { // Spaces around else.
+}
+while (test) {} // There is usually no space inside parentheses.
+switch (i) {
+for (int i = 0; i < 5; ++i) {
+// Loops and conditions may have spaces inside parentheses, but this
+// is rare. Be consistent.
+switch ( i ) {
+if ( test ) {
+for ( int i = 0; i < 5; ++i ) {
+// For loops always have a space after the semicolon. They may have a space
+// before the semicolon, but this is rare.
+for ( ; i < 5 ; ++i) {
+ ...
+
+// Range-based for loops always have a space before and after the colon.
+for (auto x : counts) {
+ ...
+}
+switch (i) {
+ case 1: // No space before colon in a switch case.
+ ...
+ case 2: break; // Use a space after a colon if there's code after it.
+
+
+Operators
+ +// Assignment operators always have spaces around them. +x = 0; + +// Other binary operators usually have spaces around them, but it's +// OK to remove spaces around factors. Parentheses should have no +// internal padding. +v = w * x + y / z; +v = w*x + y/z; +v = w * (x + z); + +// No spaces separating unary operators and their arguments. +x = -5; +++x; +if (x && !y) + ... ++ +
Templates and Casts
+ +// No spaces inside the angle brackets (< and >), before +// <, or between >( in a cast +std::vector<string> x; +y = static_cast<char*>(x); + +// Spaces between type and pointer are OK, but be consistent. +std::vector<char *> x; ++ +
Vertical Whitespace
+ +Minimize use of vertical whitespace.
+This is more a principle than a rule: don't use blank +lines when you don't have to. In particular, don't put +more than one or two blank lines between functions, +resist starting functions with a blank line, don't end +functions with a blank line, and be discriminating with +your use of blank lines inside functions.
+ +The basic principle is: The more code that fits on one +screen, the easier it is to follow and understand the +control flow of the program. Of course, readability can +suffer from code being too dense as well as too spread +out, so use your judgement. But in general, minimize use +of vertical whitespace.
+ +Some rules of thumb to help when blank lines may be +useful:
+ +-
+
- Blank lines at the beginning or end of a function + very rarely help readability. + +
- Blank lines inside a chain of if-else blocks may + well help readability. +
Exceptions to the Rules
+ +The coding conventions described above are mandatory. +However, like all good rules, these sometimes have exceptions, +which we discuss here.
+ + + +Existing Non-conformant Code
+ +You may diverge from the rules when dealing with code that +does not conform to this style guide.
+If you find yourself modifying code that was written +to specifications other than those presented by this +guide, you may have to diverge from these rules in order +to stay consistent with the local conventions in that +code. If you are in doubt about how to do this, ask the +original author or the person currently responsible for +the code. Remember that consistency includes +local consistency, too.
+ +Windows Code
+ +Windows +programmers have developed their own set of coding +conventions, mainly derived from the conventions in Windows +headers and other Microsoft code. We want to make it easy +for anyone to understand your code, so we have a single set +of guidelines for everyone writing C++ on any platform.
+It is worth reiterating a few of the guidelines that +you might forget if you are used to the prevalent Windows +style:
+ +-
+
- Do not use Hungarian notation (for example, naming
+ an integer
iNum). Use the Google naming + conventions, including the.ccextension + for source files.
+
+ - Windows defines many of its own synonyms for
+ primitive types, such as
DWORD, +HANDLE, etc. It is perfectly acceptable, + and encouraged, that you use these types when calling + Windows API functions. Even so, keep as close as you + can to the underlying C++ types. For example, use +const TCHAR *instead of +LPCTSTR.
+
+ - When compiling with Microsoft Visual C++, set the + compiler to warning level 3 or higher, and treat all + warnings as errors. + +
- Do not use
#pragma once; instead use + the standard Google include guards. The path in the + include guards should be relative to the top of your + project tree.
+
+ - In fact, do not use any nonstandard extensions,
+ like
#pragmaand__declspec, + unless you absolutely must. Using +__declspec(dllimport)and +__declspec(dllexport)is allowed; however, + you must use them through macros such as +DLLIMPORTandDLLEXPORT, so + that someone can easily disable the extensions if they + share the code.
+
However, there are just a few rules that we +occasionally need to break on Windows:
+ +-
+
- Normally we forbid + the use of multiple implementation inheritance; + however, it is required when using COM and some ATL/WTL + classes. You may use multiple implementation + inheritance to implement COM or ATL/WTL classes and + interfaces. + +
- Although you should not use exceptions in your own
+ code, they are used extensively in the ATL and some
+ STLs, including the one that comes with Visual C++.
+ When using the ATL, you should define
+
_ATL_NO_EXCEPTIONSto disable exceptions. + You should investigate whether you can also disable + exceptions in your STL, but if not, it is OK to turn on + exceptions in the compiler. (Note that this is only to + get the STL to compile. You should still not write + exception handling code yourself.)
+
+ - The usual way of working with precompiled headers
+ is to include a header file at the top of each source
+ file, typically with a name like
StdAfx.h+ orprecompile.h. To make your code easier + to share with other projects, avoid including this file + explicitly (except inprecompile.cc), and + use the/FIcompiler option to include the + file automatically.
+
+ - Resource headers, which are usually named
+
resource.hand contain only macros, do not + need to conform to these style guidelines.
+
Parting Words
+ +Use common sense and BE CONSISTENT.
+ +If you are editing code, take a few minutes to look at the
+code around you and determine its style. If they use spaces
+around their if clauses, you should, too. If their
+comments have little boxes of stars around them, make your
+comments have little boxes of stars around them too.
The point of having style guidelines is to have a common +vocabulary of coding so people can concentrate on what you are +saying, rather than on how you are saying it. We present global +style rules here so people know the vocabulary. But local style +is also important. If code you add to a file looks drastically +different from the existing code around it, the discontinuity +throws readers out of their rhythm when they go to read it. Try +to avoid this.
+ + + +OK, enough writing about writing code; the code itself is much +more interesting. Have fun!
+ ++ +