Conventions
None of these things are absolute; there’s always room for special cases with
special considerations. However, these coding conventions should describe
how this code base generally looks and works.
Superficial
- Files are indented using tabs.
- Opening curly braces go at the end of the line.
- Never align, just create new indentation levels; for example, a multi-line
function call should look like this:
SomeNamespace::someLongFunctionName(
SomePossiblyVeryLongExpression(),
10, 20);
- There’s a “soft” line length limit of 80 columns; lines can be longer, but
not significantly longer.
- Multi-line function parameter lists are indented twice, to visually separate
them from the body:
void someLongFunctionName(
int firstArgument,
int secondArgument) {
whatever;
}
Names
- Classes and structs are PascalCase.
- Methods and free functions are camelCase.
- Local variables are camelCase.
- Class member variables are camelCase_ (with the trailing underscore).
- Struct member variables are camelCase (without the trailing underscore).
- Constants are UPPER_SNAKE_CASE (no trailing underscore) everywhere.
Structure
- Classes are structured with public first, then protected, then private.
- Each section (public, protected, private) of a class starts with the member functions,
then the static member functions, then the member variables.
- Structs don’t contain private or protected fields.
- Structs starts with the member variables, then member functions, then static member functions.
- Headers are named
*.h
, source files are named *.cc
.
Behaviour
- In general, use
unique_ptr
and make_unique
for owning pointers.
- References and raw pointers should always be non-owning.
- Only use
shared_ptr
when you can’t get away from shared ownership.
- In the case of cycles, try to make ownership hierarchical; e.g the parent
has a
unique_ptr
to the child, while the child only has a reference
or raw pointer to the parent.
- When the parent and child are in different headers, the child’s header should
forward declare the parent, while the parent’s header can include the child’s
header. Cyclic includes are evil.
- In source files which act as the implementation of a header, the very first
substantial line should include the corresponding header.
- All headers should have a corresponding source file, even if that source file
is empty except for the include. This is to avoid include ordering issues.
Rationale
While a lot of this is just because we need to standardize on something,
some of the points have pretty good reasons.
- I view structs as “mainly data”; the reason you have a struct is to conveniently
put different variables together. Classes, on the other hand, are “mainly behaviour”,
so their member variables (to the degree that they have public members at all)
should be de-emphasized.
- Classes should start with their public members because that’s the only thing
other components care about. It’s odd to hide away the public interface behind
a wall of implementation details.