Revision 1.0
Krishna KumarC++ is the main development language for most of our projects. 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. One way in which we keep the code base manageable is by enforcing consistency .
Note that this guide is not a C++ tutorial.
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.
Remember that a maintaining a consistent style is often more important than doing every little detail in the way you think best.
_
). C++ files should end in
.cc
and
header files should end in
.h
. Follow the conventions
of your project.
MpmParticleClass
,
MpmParticleEnum
.
local_variable
,
member_variable_
.
particle_function()
,
particle_method()
,
member_variable()
,
set_member_variable()
.
In general, every
.cc
file should have an associated
.h
file. There are some common exceptions, such as unittests
and small
.cc
files containing just a
main()
function.
Correct use of header files can make a huge difference to the readability, size and performance of your code.
The following rules will guide you through the various pitfalls of using header files.
#define
guards to
prevent multiple inclusion. The format of the symbol name
should be
<PROJECT>
_
<PATH>
_
<FILE>
_H_
.
#include
s.
.h
, your
project's
.h
.
.cc
files are encouraged,
especially when using static variables. With named namespaces,
choose the name based on the project, and possibly its path.
Do not use a
using-directive
.
Do not use inline namespaces.
constexpr
:
they have no dynamic initialization or destruction.
struct
only for passive objects that carry data;
everything else is a
class
.
public
.
Interface
suffix.
private
, and provide
access to them through accessor functions as needed.
Use
protected
only when using it as a common data
for implementers of the base class.
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 need not be
private
.
public:
before
private:
, methods
before data members (variables), etc.
const
. Use a pointer to modify an object.
static_cast<>()
. Do not use other cast formats
like
int y = (int)x;
or
int y = int(x);
.
++i
) of the increment and
decrement operators with iterators and other template objects.
const
whenever it makes sense.
With C++11,
constexpr
is a better choice for some uses of const.
More information
about const correctness.
constexpr
to define true constants or to ensure constant initialization.
int
is generally 32bits. If your variable represents a
value that could ever be greater than or equal to 2^31, use a 64-bit
type such as
int64_t
from
<stdint.h>
.
const
variables to macros.
0
for integers,
0.0
for reals,
nullptr
(or
NULL
) for pointers,
and
'\0'
for chars.
auto
to avoid type names that are just clutter.
Continue to use manifest type declarations when it helps readability,
and never use
auto
for anything but local variables.
std::for_each
when
iterating through all the elements in a container, use these whenever
possible. You can also use itertor based for loop.
Though a pain to write, comments are absolutely vital to keeping our code readable. 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.
TODO
comments for code that is temporary, a
short-term solution, or good-enough but not perfect.
Coding style and formatting are pretty arbitrary, but a project is much easier to follow if everyone uses the same style. Individuals may not agree with every aspect of the formatting rules, and some of the rules may take some getting used to, but it is important that all project contributors follow the style rules so that they can all read and understand everyone's code easily.
To help you format code correctly, there are some tools available. See Formatting Tools for more information.
{}
or
continue
.
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.
cued.emacs
to initialise emacs to confirm to this style guide.
~/.emacs
file.
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!