Revision 3.245
Benjy WeinbergerHooray! Now you know you can expand points to get more details. Alternatively, there's an "expand all" at the top of this document.
C++ is the main development language 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.
One way in which we keep the code base manageable is by enforcing consistency. It is very important that any programmer be able to look at another's code and quickly understand it. Maintaining a uniform style and following conventions means that we can more easily use "pattern-matching" to infer what various symbols are and what invariants are true about them. Creating common, required idioms and patterns makes code much easier to understand. In some cases there might be good arguments for changing certain style rules, but we nonetheless keep things as they are in order to preserve consistency.
Another issue this guide addresses is that of C++ feature bloat. C++ is a huge language with many advanced features. In some cases we constrain, or even ban, use of certain features. We do this to keep code simple and to avoid the various common errors and problems that these features can cause. This guide lists these features and explains why their use is restricted.
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.
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.
#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:
#includes.
#include
lines can often be replaced with forward declarations of whatever
symbols are actually used by the client code.
#includes force the compiler to open
more files and process more input.#include is needed for a given piece of code,
particularly when implicit conversion operations are involved. In
extreme cases, replacing an #include with a forward
declaration can silently change the meaning of code.#includeing the header.std::
usually yields undefined behavior.#include that header.#include its
header file.#include the appropriate header.#include.#include the file that actually provides the
declarations/definitions you need; do not rely on the symbol being
brought in transitively via headers not directly included. One
exception is that myfile.cc may rely on
#includes and forward declarations from its corresponding
header file myfile.h.
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.
-inl.h suffix to define
complex inline functions when needed.
The definition of an inline function needs to be in a header
file, so that the compiler has the definition available for
inlining at the call sites. However, implementation code
properly belongs in .cc files, and we do not like
to have much actual code in .h files unless there
is a readability or performance advantage.
If an inline function definition is short, with very little,
if any, logic in it, you should put the code in your
.h file. For example, accessors and mutators
should certainly be inside a class definition. More complex
inline functions may also be put in a .h file for
the convenience of the implementer and callers, though if this
makes the .h file too unwieldy you can instead
put that code in a separate -inl.h file.
This separates the implementation from the class definition,
while still allowing the implementation to be included where
necessary.
Another use of -inl.h files is for definitions of
function templates. This can be used to keep your template
definitions easy to read.
Do not forget that a -inl.h file requires a
#define guard just
like any other header file.
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 non-const
pointers. 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.
.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
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 (preferred location
— see details below)..h files..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 often in the same
directory (e.g. base/basictypes_test.cc and
base/basictypes.h), but can 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.
For example, the includes in
google-awesome-project/src/foo/internal/fooserver.cc
might look like this:
.cc files are encouraged. With
named namespaces, choose the name based on the
project, and possibly its path.
Do not use a Namespaces provide a (hierarchical) axis of naming, in addition to the (also hierarchical) name axis provided by classes.
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.
Namespaces can be confusing, because they provide an additional (hierarchical) axis of naming, in addition to the (also hierarchical) name axis provided by classes.
Use of unnamed namespaces in header files can easily cause violations of the C++ One Definition Rule (ODR).
Use namespaces according to the policy described below. Terminate namespaces with comments as shown in the given examples.
.cc files, to avoid runtime naming
conflicts:
However, file-scope declarations that are associated with a particular class may be declared in that class as types, static data members or static member functions rather than as members of an unnamed namespace.
.h
files.
Named namespaces should be used as follows:
The typical .cc file might have more
complex detail, including the need to reference classes
in other namespaces.
std, not even forward declarations of
standard library classes. Declaring entities in
namespace std is undefined behavior,
i.e., not portable. To declare entities from the
standard library, include the appropriate header
file.
.cc file, and in functions,
methods or classes in .h files.
.cc file, anywhere inside the named
namespace that wraps an entire .h file,
and in functions and methods.
Note that an alias in a .h file is visible to everyone #including that file, so public headers (those available outside a project) and headers transitively #included by them, should avoid defining aliases, as part of the general goal of keeping public APIs as small as possible.
.cc file to avoid including the nested class
definition in the enclosing class declaration, since the
nested class definition is usually only relevant to the
implementation.
Foo::Bar* pointer will have to
include the full class declaration for Foo.
Sometimes it is useful, or even necessary, 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.
Functions defined in the same compilation unit as production classes may introduce unnecessary coupling and link-time dependencies when directly called from other compilation units; static member functions are particularly susceptible to this. Consider extracting a new class, or placing the functions in a namespace possibly in a separate library.
If you must define a nonmember function and it is only
needed in its .cc file, use an unnamed
namespace or static
linkage (eg static int Foo() {...}) to limit
its scope.
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.
Note that gcc implements for (int i = 0; i
< 10; ++i) correctly (the scope of i is
only the scope of the for loop), so you can then
reuse i in another for loop in the
same scope. It also correctly scopes declarations in
if and while statements, e.g.
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.
It may be more efficient to declare such a variable used in a loop outside that loop:
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 static POD 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.
Likewise, 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.
As a result we only allow static variables to contain POD data. This
rule completely disallows 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.
main(), possibly breaking some implicit
assumptions in the constructor code. For instance,
gflags
will not yet have been initialized.
Init() method.
new a
class object with no arguments. It is always called when
calling new[] (for arrays).
If your class defines member variables and has no other constructors you must define a default constructor (one that takes no arguments). It should preferably initialize the object in such a way that its internal state is consistent and valid.
The reason for this is that if you have no other constructors and do not define a default constructor, the compiler will generate one for you. This compiler generated constructor may not initialize your object sensibly.
If your class inherits from an existing class but you add no new member variables, you are not required to have a default constructor.
explicit for constructors with
one argument.
Foo::Foo(string name) and then pass a string to a
function that expects a Foo, the constructor will
be called to convert the string into a Foo and
will pass the Foo to your function for you. This
can be convenient but is also a source of trouble when things
get converted and new objects created without you meaning them
to. Declaring a constructor explicit prevents it
from being invoked implicitly as a conversion.
We require all single argument constructors to be
explicit. Always put explicit in front of
one-argument constructors in the class definition:
explicit Foo(string name);
The exception is copy constructors, which, in the rare
cases when we allow them, should probably not be
explicit.
Classes that are intended to be
transparent wrappers around other classes are also
exceptions.
Such exceptions should be clearly marked with comments.
DISALLOW_COPY_AND_ASSIGN.
CopyFrom()-style workarounds because they combine
construction with copying, the compiler can elide them in some
contexts, and they make it easier to avoid heap allocation.
Few classes need to be copyable. Most should have neither a copy constructor nor an assignment operator. In many situations, a pointer or reference will work just as well as a copied value, with better performance. For example, you can pass function parameters by reference or pointer instead of by value, and you can store pointers rather than objects in an STL container.
If your class needs to be copyable, prefer providing a copy method,
such as CopyFrom() or Clone(), rather than
a copy constructor, because such methods cannot be invoked
implicitly. If a copy method is insufficient in your situation
(e.g. for performance reasons, or because your class needs to be
stored by value in an STL container), provide both a copy
constructor and assignment operator.
If your class does not need a copy constructor or assignment
operator, you must explicitly disable them.
To do so, add dummy declarations for the copy constructor and
assignment operator in the private: section of your
class, but do not provide any corresponding definition (so that
any attempt to use them results in a link error).
For convenience, a DISALLOW_COPY_AND_ASSIGN macro
can be used:
Then, in class Foo:
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.
public.
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.
When redefining an inherited virtual function, explicitly
declare it virtual in the declaration of the
derived class. Rationale: If virtual is
omitted, the reader has to check all ancestors of the
class in question to determine if the function is virtual
or not.
Interface suffix.
Interface suffix.
Interface suffix.
A class is a pure interface if it meets the following requirements:
= 0") methods
and static methods (but see below for destructor).
Interface suffix.
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.
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.
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.
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.
+ and
/ operate on the class as if it were a built-in
type.
int). Overloaded operators are more playful
names for functions that are less-colorfully named, such as
Equals() or Add(). For some
template functions to work correctly, you may need to define
operators.
Equals() is much
easier than searching for relevant invocations of
==.
Foo + 4 may do one thing,
while &Foo + 4 does something totally
different. The compiler does not complain for either of
these, making this very hard to debug.
operator&, it
cannot safely be forward-declared.
In general, do not overload operators. The assignment operator
(operator=), in particular, is insidious and
should be avoided. You can define functions like
Equals() and CopyFrom() if you
need them. Likewise, avoid the dangerous
unary operator& at all costs, if there's
any possibility the class might be forward-declared.
However, there may be rare cases where you need to overload
an operator to interoperate with templates or "standard" C++
classes (such as operator<<(ostream&, const
T&) for logging). These are acceptable if fully
justified, but you should try to avoid these whenever
possible. In particular, do not overload operator==
or operator< just so that your class can be
used as a key in an STL container; instead, you should
create equality and comparison functor types when declaring
the container.
Some of the STL algorithms do require you to overload
operator==, and you may do so in these cases,
provided you document why.
See also Copy Constructors and Function Overloading.
private, and provide
access to them through accessor functions as needed (for
technical reasons, we allow data members of a test fixture class
to be protected when using
Google Test). Typically a variable would be
called foo_ and the accessor function
foo(). You may also want a mutator function
set_foo().
Exception: static const data members (typically
called kFoo) need not be private.
The definitions of accessors are usually inlined in the header file.
See also Inheritance and Function Names.
public: before private:, methods
before data members (variables), etc.
Your class definition should start with its public:
section, followed by its protected: section and
then its private: section. If any of these sections
are empty, omit them.
Within each section, the declarations generally should be in the following order:
static const data members)static const data members)
Friend declarations should always be in the private section, and
the DISALLOW_COPY_AND_ASSIGN macro invocation
should be at the end of the private: section. It
should be the last thing in the class. See Copy Constructors.
Method definitions in the corresponding .cc file
should be the same as the declaration order, as much as possible.
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.
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.
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.
scoped_ptr
is great. You should only use std::tr1::shared_ptr
with a non-const referent when it is truly necessary to share ownership
of an object (e.g. inside an STL container). You should never use
auto_ptr.
auto_ptr) can be nonobvious and confusing. The
exception-safety benefits of smart pointers are not decisive, since
we do not allow exceptions.
scoped_ptrauto_ptrshared_ptrshared_ptr<const
T>). Reference-counted pointers with non-const referents
can occasionally be the best design, but try to rewrite with single
owners where possible.
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.
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.
const.
int foo(int
*pval). In C++, the function can alternatively
declare a reference parameter: int foo(int
&val).
(*pval)++. Necessary for some applications like
copy constructors. Makes it clear, unlike with pointers, that
a null pointer is not a possible value.
Within function parameter lists all references must be
const:
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:
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.
You may write a function that takes a
const string& and overload it with another that
takes const char*.
AppendString(), AppendInt() rather
than just Append().
While the cons above are not that onerous, they still outweigh the (small) benefits of default arguments over function overloading. So except as described below, we require all arguments to be explicitly specified.
One specific exception is when the function is a static function (or in an unnamed namespace) in a .cc file. In this case, the cons don't apply since the function's use is so localized.
Another specific exception is when default arguments are used to simulate variable-length argument lists.
alloca().
alloca() are very
efficient.
scoped_ptr/scoped_array.
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.
Init() method, but these require heap
allocation or a new "invalid" state, respectively.throw statement 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() calls g() calls
h(), and h throws an exception
that f catches, g has to be
careful or it may not clean up properly.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.
There is an exception to this rule (no pun intended) for Windows code.
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
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:
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.
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.
static_cast<>(). Do not use
other cast formats like int y = (int)x; or
int y = int(x);.
(int)3.5) and sometimes you are doing a
cast (e.g., (int)"hello"); C++ casts
avoid this. Additionally C++ casts are more visible when
searching for them.
Do not use C-style casts. Instead, use these C++-style casts.
static_cast as the equivalent of a
C-style cast that does value conversion, or when you need to explicitly up-cast
a pointer from a class to its superclass.
const_cast to remove the const
qualifier (see const).
reinterpret_cast to 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.
printf() and
scanf().
printf either.) Streams
have automatic constructors and destructors that open and close the
relevant files.
pread(). Some formatting (particularly the common
format string idiom %.*s) is difficult if not
impossible to do efficiently using streams without using
printf-like hacks. Streams do not support operator
reordering (the %1s directive), which is helpful for
internationalization.
Do not use streams, except where required by a logging interface.
Use printf-like routines instead.
There are various pros and cons to using streams, but in this case, as in many other cases, consistency trumps the debate. Do not use streams in your code.
There has been debate on this issue, so this explains the
reasoning in greater depth. Recall the Only One Way
guiding principle: we want to make sure that whenever we
do a certain type of I/O, the code looks the same in all
those places. Because of this, we do not want to allow
users to decide between using streams or using
printf plus Read/Write/etc. Instead, we should
settle on one or the other. We made an exception for logging
because it is a pretty specialized application, and for
historical reasons.
Proponents of streams have argued that streams are the obvious choice of the two, but the issue is not actually so clear. For every advantage of streams they point out, there is an equivalent disadvantage. The biggest advantage is that you do not need to know the type of the object to be printing. This is a fair point. But, there is a downside: you can easily use the wrong type, and the compiler will not warn you. It is easy to make this kind of mistake without knowing when using streams.
The compiler does not generate an error because
<< has been overloaded. We discourage
overloading for just this reason.
Some say printf formatting is ugly and hard to
read, but streams are often no better. Consider the following
two fragments, both with the same typo. Which is easier to
discover?
And so on and so forth for any issue you might bring up. (You could argue, "Things would be better with the right wrappers," but if it is true for one scheme, is it not also true for the other? Also, remember the goal is to make the language smaller, not add yet more machinery that someone has to learn.)
Either path would yield different advantages and
disadvantages, and there is not a clearly superior
solution. The simplicity doctrine mandates we settle on
one of them though, and the majority decision was on
printf + read/write.
++i) of the increment and
decrement operators with iterators and other template objects.
++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).
++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?
for
loops. Some find post-increment easier to read, since the
"subject" (i) precedes the "verb" (++),
just like in English.
const whenever it makes sense.
With C++11,
constexpr is a better choice for some uses of const.
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;
};).
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:
const.
const whenever
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-const methods, and do not return a
non-const pointer or non-const
reference to a data member.
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.
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!
constexpr
to define true constants or to ensure constant initialization.
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.
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.
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.
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.
short is 16 bits,
int is 32 bits, long is 32 bits and
long long is 64 bits.
<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.
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:
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.
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):
| 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 %zd |
Note 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. It is still possible, as usual,
to include length specifiers, etc., after the
% when using the PRI*
macros. So, e.g. printf("x = %30"PRIuS"\n",
x) would expand on 32-bit Linux to
printf("x = %30" "u" "\n", x), which the
compiler will treat as printf("x = %30u\n",
x).
sizeof(void *) !=
sizeof(int). Use intptr_t if
you want a pointer-sized integer.
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()).
LL or ULL suffixes as
needed to create 64-bit constants. For example:
#ifdef _LP64 to choose between
the code variants. (But please avoid this if
possible, and keep any such changes localized.)
const variables to macros.
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.
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.
The following usage pattern will avoid many problems with macros; if you use macros, follow it whenever possible:
.h file.
#define macros right before you use them,
and #undef them right after.
#undef an existing macro before
replacing it with your own; instead, pick a name that's
likely to be unique.
## to generate function/class/variable
names.
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
and NULL (and, for C++11, 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(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.
auto to avoid type names that are just clutter.
Continue to use manifest type declarations when it helps readability,
and never use auto for anything but local variables.
auto will be given
a type that matches that of the expression used to initialize
it. You can use auto either to initialize a
variable by copying, or to bind a reference.
C++ type names can sometimes be long and cumbersome,
especially when they involve templates or namespaces. In a statement like
Without auto we are sometimes forced to write a
type name twice in the same expression, adding no value
for the reader, as in
Using auto makes it easier to use intermediate
variables when appropriate, by reducing the burden of writing
their types explicitly.
Sometimes code is clearer when types are manifest, especially when
a variable's initialization depends on things that were declared
far away. In an expression like
i's type is, if x
was declared hundreds of lines earlier.
Programmers have to understand the difference between auto
and const auto& or they'll get copies when
they didn't mean to.
The interaction between auto and C++11
brace-initialization can be confusing. (C++11 brace-initialization
isn't an approved feature, but this may become relevant when and
if it is permitted.) The declarations
x is
an int, while y is
an initializer_list. The same applies to other
normally-invisible proxy types.
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, for local variables only.
Do not use auto for file-scope or namespace-scope
variables, or for class members.
The auto keyword is also used in an unrelated
C++11 feature: it's part of the syntax for a new kind of
function declaration with a trailing return type. Function
declarations with trailing return types are not permitted.
boost/call_traits.hpp
boost/compressed_pair.hpp
boost/ptr_container except
serialization and wrappers for containers not in the C++03
standard (ptr_circular_buffer.hpp and
ptr_unordered*)
boost/array.hpp
boost/graph,
except serialization (adj_list_serialize.hpp) and
parallel/distributed algorithms and data structures
(boost/graph/parallel/* and
boost/graph/distributed/*).
boost/property_map, except
parallel/distributed property maps
(boost/property_map/parallel/*).
boost/iterator/iterator_adaptor.hpp,
boost/iterator/iterator_facade.hpp, and
boost/function_output_iterator.hppboost/polygon/voronoi_builder.hpp,
boost/polygon/voronoi_diagram.hpp, and
boost/polygon/voronoi_geometry_type.hppThe 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 (gcc, icc, clang, Eclipse, etc.).
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.
auto (for local variables only).constexpr (for ensuring constants).>> with no intervening space to
close multiple levels of template arguments, as in
set<list<string>>,
where C++03 required a space as in
set<list<string> >.
for loops.LL and ULL suffixes on
numeric literals to guarantee that their type is at least 64 bits
wide.min, max, and minmax
whose signatures contain initializer lists.nullptr and nullptr_t.static_assert.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.
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. Examples of well-chosen names:
Poorly-chosen names use ambiguous abbreviations or arbitrary characters that do not convey meaning:
Type and variable names should typically be nouns: e.g.,
FileOpener,
num_errors.
Function names should typically be imperative (that is they
should be commands): e.g., OpenFile(),
set_num_errors(). There is an exception for
accessors, which, described more completely in Function Names, should be named
the same as the variable they access.
Do not use abbreviations unless they are extremely well known outside your project. For example:
Never abbreviate by leaving out letters:
_) 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.
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. However, if your inline functions
include a lot of code, they may go into a third file that
ends in -inl.h. In a class with a lot of inline
code, your class could have three files:
See also the section -inl.h Files
MyExcitingClass, MyExcitingEnum.
The names of all types — classes, structs, typedefs, and enums — 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:
my_exciting_local_variable,
my_exciting_member_variable_.
For example:
Data members (also called instance variables or member variables) are lowercase with optional underscores like regular variable names, but always end with a trailing underscore.
Data members in structs should be named like regular variables without the trailing underscores that data members in classes have.
See Structs vs. Classes for a discussion of when to use a struct versus a class.
There are no special requirements for global variables,
which should be rare in any case, but if you use one,
consider prefixing it with g_ or some other
marker to easily distinguish it from local variables.
k followed by mixed case:
kDaysInAWeek.
All compile-time constants, whether they are declared locally,
globally, or as part of a class, follow a slightly different
naming convention from other variables. Use a k
followed by words with uppercase first letters:
MyExcitingFunction(),
MyExcitingMethod(),
my_exciting_member_variable(),
set_my_exciting_member_variable().
Functions should start with a capital letter and have a capital letter for each new word. No underscores.
If your function crashes upon an error, you should append OrDie to the function name. This only applies to functions which could be used by production code and to errors that are reasonably likely to occur during normal operation.
Accessors and mutators (get and set functions) should match
the name of the variable they are getting and setting. This
shows an excerpt of a class whose instance variable is
num_entries_.
You may also use lowercase letters for other very short inlined functions. For example if a function were so cheap you would not cache the value if you were calling it in a loop, then lowercase naming would be acceptable.
google_awesome_project.
See Namespaces for a discussion of namespaces and how to name them.
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.
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.
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.
bigopen() open() uint typedef bigpos struct or class, follows form of
pos sparse_hash_map LONGLONG_MAX INT_MAX 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!
// 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.
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.
Every file should have a comment at the top describing its contents.
Generally a .h file will describe the classes
that are declared in the file with an overview of what they
are for and how they are used. A .cc file
should contain more information about implementation details
or discussions of tricky algorithms. If you feel the
implementation details or a discussion of the algorithms
would be useful for someone reading the .h,
feel free to put it there instead, but mention in the
.cc that the documentation is in the
.h file.
Do not duplicate comments in both the .h and
the .cc. Duplicated comments diverge.
If you have already described a class in detail in the comments at the top of your file feel free to simply state "See comment at top of file for a complete description", but be sure to have some sort of comment.
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.
Every function declaration should have comments immediately preceding it that describe what the function does and how to use it. 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:
Here is an example:
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.
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.
Each function definition should have a comment describing what the function does if there's anything tricky about how it does its job. 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.
Each class data member (also called an instance variable or member variable) should have a comment describing what it is used for. If the variable can take sentinel values with special meanings, such as a null pointer or -1, document this. For example:
As with data members, all global variables should have a comment describing what they are and what they are used for. For example:
Tricky or complicated code blocks should have comments before them. Example:
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:
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:
When you pass in a null pointer, boolean, or literal integer values to functions, you should consider adding a comment about what they are, or make your code self-documenting by using constants. For example, compare:
versus:
Or alternatively, constants or self-describing variables:
Note that you should never describe the code itself. Assume that the person reading the code knows C++ better than you do, even though he or she does not know what you are trying to do:
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 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, or other
identifier
of the person who can best provide context about the problem
referenced by the TODO. A colon is optional. The main
purpose is to have a consistent TODO format that can be
searched to find the person who can provide more details upon request.
A TODO is not a commitment that the person referenced
will fix the problem. Thus when you create a TODO, it is
almost always your
name
that is given.
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.").
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.
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.
We recognize that this rule is controversial, but so much existing code already adheres to it, and we feel that consistency is important.
80 characters is the maximum.
Exception: if a comment line contains an example command or a literal URL longer than 80 characters, that line may be longer than 80 characters for ease of cut and paste.
Exception: an #include statement with a long
path may exceed 80 columns. Try to avoid situations where this
becomes necessary.
Exception: you needn't be concerned about header guards that exceed the maximum length.
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" is the
Unicode zero-width no-break space character, which would be
invisible if included in the source as straight UTF-8.
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.
Functions look like this:
If you have too much text to fit on one line:
or if you cannot fit even the first parameter:
Some points to note:
If some parameters are unused, comment out the variable name in the function definition:
Function calls have the following format:
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:
If the function has many arguments, consider having one per line if this makes the code more readable:
Arguments may optionally all be placed on subsequent lines, with one line per argument:
In particular, this should be done if the function signature is so long that it cannot fit within the maximum line length.
else
keyword belongs on a new line.
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 you prefer you may add spaces inside the parentheses:
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.
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.
This is not allowed when the if statement has an
else:
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.
However, if one part of an if-else
statement uses curly braces, the other part must too:
{}
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:
Empty loop bodies should use {} or
continue, but not a single semicolon.
The following are examples of correctly-formatted pointer and reference expressions:
Note that:
* or
&.
When declaring a pointer variable or argument, you may place the asterisk adjacent to either the type or to the variable name:
You should do this consistently within a single file, so, when modifying an existing file, use the style in that file.
In this example, the logical AND operator is always at the end of the lines:
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 expression with
parentheses.
Use parentheses in return expr; only where you would use
them in x = expr;.
= or ().
You may choose between = and (); the
following are all correct:
Even when preprocessor directives are within the body of indented code, the directives should start at the beginning of the line.
public, protected and
private order, each indented one space.
The basic format for a class declaration (lacking the comments, see Class Comments for a discussion of what comments are needed) is:
Things to note:
public:, protected:, and
private: keywords should be indented one
space.
public section should be first, followed by
the protected and finally the
private section.
There are two acceptable formats for initializer lists:
or
Namespaces do not add an extra level of indentation. For example, use:
Do not indent within a namespace:
When declaring nested namespaces, put each namespace on its own line.
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).
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:
The coding conventions described above are mandatory. However, like all good rules, these sometimes have exceptions, which we discuss here.
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.
It is worth reiterating a few of the guidelines that you might forget if you are used to the prevalent Windows style:
iNum). Use the Google naming conventions,
including the .cc extension for source files.
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.
#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.
#pragma and __declspec, unless you
absolutely must. Using __declspec(dllimport) and
__declspec(dllexport) is allowed; however, you
must use them through macros such as DLLIMPORT
and DLLEXPORT, 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:
_ATL_NO_EXCEPTIONS to
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.)
StdAfx.h or
precompile.h. To make your code easier to share
with other projects, avoid including this file explicitly
(except in precompile.cc), and use the
/FI compiler option to include the file
automatically.
resource.h and contain only macros, do not need
to conform to these style guidelines.
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!
Revision 3.245
Benjy Weinberger