Revision 4.1
Tim PenheyHooray! Now you know you can expand points to get more details. Alternatively, there's an "expand all" at the top of this document.
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.
Note that this guide is not a C++ tutorial: we assume that the reader is familiar with the language.
In general, every .cpp file should have an associated
.h file. There are some common exceptions, such as
unittests and small .cpp 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:
#include when a forward declaration
would suffice.
When you include a header file you introduce a dependency that will cause your code to be recompiled whenever the header file changes. If your header file includes other header files, any change to those files will cause any code that includes your header to be recompiled. Therefore, we prefer to minimize includes, particularly includes of header files in other header files.
You can significantly reduce the number of header files you
need to include in your own header files by using forward
declarations. For example, if your header file uses the
File class in ways that do not require access to
the declaration of the File class, your header
file can just forward declare class File; instead
of having to #include "file/base/file.h".
How can we use a class Foo in a header file
without access to its definition?
Foo* or
Foo&.
Foo. (One
exception is if an argument Foo
or const Foo& has a
non-explicit, one-argument constructor,
in which case we need the full definition to support
automatic type conversion.)
Foo. This is because static data members
are defined outside the class definition.
On the other hand, you must include the header file for
Foo if your class subclasses Foo or
has a data member of type Foo.
Sometimes it makes sense to have pointer (or better,
scoped_ptr)
members instead of object members. However, this complicates code
readability and imposes a performance penalty, so avoid doing
this transformation if the only purpose is to minimize includes
in header files.
Of course, .cpp files typically do require the
definitions of the classes they use, and usually have to
include several header files.
Foo in your source file, you
should bring in a definition for Foo yourself,
either via an #include or via a forward declaration. Do not
depend on the symbol being brought in transitively via headers
not directly included. One exception is if Foo
is used in myfile.cpp, it's ok to #include (or
forward-declare) Foo in myfile.h,
instead of myfile.cpp.
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 .cpp 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,
my-awesome-project/src/base/logging.h
should be included as
In dir/foo.cpp or dir/foo_test.cpp,
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.
The preferred ordering reduces hidden dependencies. We want
every header file to be compilable on its own. The easiest
way to achieve this is to make sure that every one of them is
the first .h file #included in some
.cpp.
dir/foo.cpp and
dir2/foo2.h are often in the same
directory (e.g. base/basictypes_test.cpp and
base/basictypes.h), but can be in different
directories too.
Within each section it is nice to order the includes alphabetically.
For example, the includes in
my-awesome-project/src/foo/internal/fooserver.cpp
might look like this:
.cpp 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 spaces in header files can easily cause violations of the C++ One Definition Rule (ODR).
Use namespaces according to the policy described below.
.cpp 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. Terminate the unnamed
namespace as shown, with a comment //
namespace.
.h
files.
Named namespaces should be used as follows:
The typical .cpp 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.
.cpp file, and in functions,
methods or classes in .h files.
.cpp 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.
.cpp 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 .cpp 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:
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.
Init() method.
main(), possibly breaking some implicit
assumptions in the constructor code. For instance,
gflags
will not yet have been initialized.
Init() method. In particular,
constructors should not call virtual functions, attempt to raise
errors, access potentially uninitialized global variables, etc.
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, they 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 .cpp 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.
std::unique_ptr
is great. You should only use std::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.
unique_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
NULL is not a possible value.
Within function parameter lists all references must be
const:
In fact it is a very strong convention in Unity code that input
arguments are values or const references while output
arguments are pointers. Input parameters may be const
pointers. Non-const reference parameters are allowed
but there must be a valid reason for it, a strong preference is
given to const reference parameters.
One case when you might want an input parameter to be a
const pointer is if you want to emphasize that the
argument is not copied, so it must exist for the lifetime of the
object; it is usually best to document this in comments as
well. STL adapters such as bind2nd and
mem_fun do not permit reference parameters, so
you must declare functions with pointer parameters in these
cases, too.
You may write a function that takes a
string const& and overload it with another that
takes const char*.
AppendString(), AppendInt() rather
than just Append().
Except as described below, we require all arguments to be explicitly specified, to force programmers to consider the API and the values they are passing for each argument rather than silently accepting defaults they may not be aware of.
One specific exception is when default arguments are used to simulate variable-length argument lists.
alloca().
alloca() are very
efficient.
unique_ptr.
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 of Unity is not prepared to deal with exceptions, it is comparatively difficult to adopt new code that generates exceptions.
Given that Unity'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. Things would probably be different if we had to do it all over again from scratch.
It is useful in some unittests. 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.
In rare circumstances, it is useful even outside of tests.
Do not use RTTI, except in unittests. If you find yourself in need of writing code that behaves differently based on the class of an object, consider one of the 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.
If you think you truly cannot use those ideas, you may use RTTI. But think twice about it. :-) Then think twice again. Do not hand-implement an RTTI-like workaround. The arguments against RTTI apply just as much to workarounds like class hierarchies with type tags.
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.
dynamic_cast except in test code.
If you need to know type information at runtime in this way
outside of a unittest, you probably have a design
flaw.
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 to do so.
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.
However, do not go crazy with const. Something like
const int * const * const x; is likely
overkill, even if it accurately describes how const x is.
Focus on what's really useful to know: in this case,
const int** x is probably sufficient.
The mutable keyword is allowed but is unsafe
when used with threads, so thread safety should be carefully
considered first.
We favor the form int const* foo to
const int* foo. This keeps the const
with the type modifier (& or *).
An exception to this is const char* due to existing
C convention.
That said, while we encourage putting const after the type,
we do not require it. But be consistent with the code around
you!
int. If a program needs a variable of a different
size, use
a precise-width integer type from
<stdint.h>, such as int16_t.
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 the quantity you are representing is really a bit pattern
rather than a number, or unless you need defined
twos-complement overflow. In particular, do not use unsigned
types to say a number will never be negative. Instead, use
assertions for this.
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 for pointers, and '\0' for chars.
Use 0 for integers and 0.0 for reals.
This is not controversial.
For pointers (address values), C++11 added the nullptr
construct. This allows the compiler to do additional checks, and is the
preferred NULL pointer value.
Use '\0' for chars.
This is the correct type and also makes code more readable.
sizeof(varname) instead of
sizeof(type) whenever possible.
Use sizeof(varname) because it will update
appropriately if the type of the variable changes.
sizeof(type) may make sense in some cases,
but should generally be avoided because it can fall out of sync if
the variable's type changes.
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.hpp
The range based for is the preferred way to iterate over containers
when simple iteration is needed.
The auto keyword is acceptable within reason.
Strong enums are preferred where the integer values are not explicitly needed.
Lambda functions are acceptable within reason.
Use unique_ptr and shared_ptr from
<memory>.
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.cpp
my-useful-class.cpp
myusefulclass.cpp
myusefulclass_test.cpp // _unittest and _regtest are deprecated.
C++ files should end in .cpp 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.cpp, 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.
DAYS_IN_A_WEEK.
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 upper-case with underscores.
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.
my_awesome_project.
See Namespaces for a discussion of namespaces and how to name them.
ENUM_NAME.
Preferably, the individual enumerators should be named like
constants. The enumeration name,
UrlTableErrors, is a type, and
therefore mixed case.
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 the following items, in order:
// -*- Mode: C++; indent-tabs-mode: nil; tab-width: 2 -*-Copyright (C) 2011 Canonical Ltd)If you make significant changes to a file that someone else originally wrote, add yourself to the author line. This can be very helpful when another contributor has questions about the file and needs to know whom to contact about it.
Every file should have a comment at the top, below the copyright notice and author line, that describes the contents of the file.
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 .cpp 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
.cpp that the documentation is in the
.h file.
Do not duplicate comments in both the .h and
the .cpp. 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:
NULL.
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 NULL 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 NULL, 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 usually be written as complete sentences with proper capitalization and periods at the end. 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. Complete sentences are more readable, and they provide some assurance that the comment is complete and not an unfinished thought.
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.
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 your function is const, the const
keyword should be on the same line as the last parameter:
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:
If the function signature is so long that it cannot fit within the maximum line length, you may place all arguments on subsequent lines:
else
keyword belongs on a new line.
Note that in all cases you must have a space between the
if and the open parenthesis.
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 should place the asterisk adjacent to the type:
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. 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.
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 are not indented.
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, with the opening brace on the line following.
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.
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!