Leave the code a little cleaner after each commit
A common C++ coding style that i try to follow on my own projects to make them more consistent. It makes them easier to read the next time i look at them.
A header should include all other headers it needs and should not require any particular symbols to be defined.
The #define Guard
All header files should have include guards.
Include headers in the order below. Keep them in alphabetical order within each section.
related file. In foo.cpp this is foo.h.
C system files.
C++ system files.
other libs .h files.
project .h files.
Bigger scope warrants a more descriptive name
Do not use abbreviations in names.
Avoid abbreviations in names as they are harder to understand and it is best to use a uniform name everywhere. If something is called local_pos in one place and local_position in another it is only confusing.
Name files like_this.cpp
Filenames should be all lowercase and words separated by underscores (_). C++ files should end in .cpp and header files in .h.
Name types (classes, structs, typedefs and enums) LikeThis
Type names start with a capital letter and have a capital letter for each new word.
Name variables likeThis
First character is lowercase and then each new word start with a uppercase.
Name member variabes _likeThis
For member variables, both static and non-static use a normal variable name but put a _ first.
Name functions LikeThis
First character is capital letter and then each new word start with a capital letter .
Accessors and Mutators
Get and set functions should be in the form of Position() and SetPosition().
Name namespaces LikeThis
Name enums LikeThis and enums values LIKE_THIS
Name macros LIKE_THIS
Macros are done with all capitals and underscores between words.
How to use the styles of braces
Use Continue or break to avoid deep nesting
Try to fit matching braces on the same screen
Formating and Spacing
The newspaper metaphor
The source file should be like a newspaper article. The name should be simple but explanatory. The topmost part of the source code should provide the high-level concept and algorithms and detail should increase as we move downward, until at the end were we find the lowest level functions and details.
Use three spaces of indentation
Indent #if statements
Visual studio forces all preprocessing macros to the left. Intend macros like it is normal code.
Do not indent the entire file
When the whole file is inside one (or more) namespaces, you should not indent the entire file. It does not improve readability so instead put a comment on the closing brace.
Make data members private and use accessor functions. A variable with the name _foo has the accessor function Foo() and SetFoo().
The class should contain the sections public, protected and then private in that order. Empty sections should not be included. Within each sections declarations should be in the following order.
Typedefs and enums.
Constants (static const)
Prefer range-based for loop
Prefer passing objects by value, *, or &. Only pass a smart pointer if you wish to manipulate the ownership.
Prefer scoped lifetime by default (local, members)
For ownership prefer make_unique & uniqe_ptr
For shared ptrs use make_shared when possible.
Use // for comments and /* for disabling code
Use // for comments and avoid /* so it can be used to quickly disable a block of code.
Clean away disabled code in the source
Disabled code can be left in the source for a short time while you check that the new code works. After that the commeted out code should be removed from the file. Source control already keeps all code and these comment clutter up the code and rot away so it is better to remove it.
Comments are hints.
The main source of information is the code itself at is always up-to-date.
No high level documentation in comments
For more detailed documentation use the wiki and add a link as a comment to describe high level concepts.
Document public methods of classes.
Put interface documentation in the .h file.
Put interface (function and class) documentation in the .h file. That makes it more easy to find all the interface documentation in one place and it does not clutter up the functions itself.
Use doxygen syntax for interface documentation
Doxygen is the tool to use for documentation. /// is your friend to the end.
Comment a file
A file can have a comment at the top that describe the files content. A .h file will describe the classes that are declared in the file and give a overview of how they are used and what for. A .cpp file comment should focus on the implementation details. Do not duplicate information so if needed put it all in the header file.
Comment a class
Describe what the class is for and how it should be used. If it has already been described in the file comment refer to that one.
Comment a function declaration
In the declaration (.h) describe the what a user need to know to call the function.
Comment a function definition
In the definition describe how the function works. This should only be needed if the function does something tricky.
Comment a variable
For variables use the single line comment if it fits on one line.