This styleguide is derived from the Google C++ Style Guide and is hosted on Github. Some modifications were made to match the OpenGeoSys development needs. The original authors are Benjy Weinberger, Craig Silverstein, Gregory Eitzmann, Mark Mentovai and Tashana Landray.
Hooray! Now you know you can expand points to get more details. Alternatively, there's an "expand all" at the top of this document.
This guide comes with a configuration file for the uncrustify automatic code styler. With this tool you can restyle your source code according to this styleguide. The config file is not finished yet. For creating the config file the UniversalIndentGUI was used. See this link for instructions how to apply the formatting to your code.
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. There is only one class per header file.
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
<FILENAME_WITHOUT_ENDING>_H
.
Every file in a project should be named unique so it is
sufficient to only use the filename. For example, the file
Foo.h
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
MyClass
class in ways that do not require access to
the declaration of the MyClass
class, your header
file can just forward declare class MyClass;
instead
of having to #include "MyClass.h"
. Note the special
notation of classes inside namespaces.
instead of
Never forward declare somethin the std
namespace.
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
.
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.
Because of compiler doing optimizations you do not have to care that much about inlining. The compiler often does this for you when useful. Otherwise a decent rule of thumb is to not inline a function if it is more than 2 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.
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 only the filename itself.
Logging.h
should be included as
In Foo.cpp
order your includes as
follows:
Foo.h
.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 #include
d in some
.cpp
.
Within each section it is nice to order the includes alphabetically.
For example, the includes in
Fooserver.cpp
might look like this:
Namespaces provide a (hierarchical) axis of naming, in addition to the (also hierarchical) name axis provided by classes.
Use namespaces according to the policy described below.
Named namespaces should be used as follows:
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.
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.
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 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 variable of a class type, consider initializing a pointer (which will never be freed), from either your main() function or from pthread_once().
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.
Finally, constructors that take only an initializer_list may be
non-explicit. This is to permit construction of your type using the
assigment form for brace init lists (i.e. MyType m = {1, 2}
).
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
.
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.
Abstract
.
A class that has at least one pure virtual method ("= 0
")
is abstract, that is it cannot instantiated directly. It is used as a
base class for another class implementing that pure virtual method.
When all methods of a class are pure virtual it is considered a interface.
I
prefix.
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.
I
prefix 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.
I
only if it meets the
above requirements. We do not require the converse.
+
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.
Typically a variable would be
called _foo
and the accessor function
getFoo()
. You may also want a mutator function
setFoo()
.
Exception: static const
data members 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.
friend
classes and functions,
within reason.
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.
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.
++i
) of the increment and
decrement operators with iterators and other template objects.
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.
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 this case, because the "don't go crazy" dictum
eliminates most of the uses you'd have to be consistent with.
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!
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), there is a choice between 0
,
NULL
and nullptr
. We use nullptr
because it specifies exactly what is meant.
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.
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
, numErrors
.
Function names should typically be imperative (that is they
should be commands): e.g., openFile()
,
setNumErrors()
.
Do not use abbreviations unless they are extremely well known outside your project. For example:
Never abbreviate by leaving out letters:
_
) or dashes (-
). The name must match the
class that is defined in the file.
Examples of acceptable file names for the class MyUsefulClass
:
MyUsefulClass.h
MyUsefulClass.cpp
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
.
Inline functions must be in a .h
file. If your
inline functions are very short, they should go directly into your
.h
file.
In addition to the general naming scheme the template implementation
should be placed in a file named MyTemplateClass-impl.h
.
This file gets included at the end of the header file
MyTemplateClass.h
.
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. This is the same convention as for file namea. For example:
myExcitingLocalVariable
,
_myExcitingMemberVariable
. As an alternative you can use
lowercase names with underscores: _my_exciting_member_variable
.
But be consistent in a file!
Data members in structs should be named like regular variables without the starting underscore that data members in classes have.
See Structs vs. Classes for a discussion of when to use a struct versus a class.
doSomeStuff()
,
doSomeStuffOnThing()
,
getMyExcitingMemberVariable()
,
setMyExcitingMemberVariable()
.
Functions should start with a lowercase letter and have a capital letter for each new word. No underscores.
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
_numEntries
.
MyNamespace
.
See Namespaces for a discussion of namespaces and how to name them.
EnumName
.
Preferably, the individual enumerators should be named like macros.
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.
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. For header
file comments use Doxygen
///
or /** */
comments. Doxygen allows to
automatically generating browsable source code documentation. Additional
information like a brief description or function parameter description
can be added inside Doxygen comments with backslashed or @-prefixed
keywords like /// \brief
or /// @see
.
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:
Copyright (c) 2013, OpenGeoSys Community (http://www.opengeosys.net)
)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.
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:
nullptr
.
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 nullptr
or -1, document this.
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 nullptr
, 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:
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.
TODO
s 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.").
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.
Advantages of the Allman style are that the indented code is clearly set apart from the containing statement by lines that are almost completely whitespace, improving readability, and the closing brace lines up in the same column as the opening brace, making it easy to find matching braces
K&R style is more compact but lacks some clearness.
Functions look like this:
If you have too much text to fit on one line:
or if you cannot fit even the first parameter:
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 should be not indented.
public
section should be first, followed by
the protected
and finally the
private
section.
public slots:
should follow
public
. The signal definition signals:
should be placed at the end.
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.
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!
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 dont's 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.