Programming‎ > ‎

Code Style

Leave the code a little cleaner after each commit

Introduction

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.

Header Files
Self-contained Headers
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 order
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.

Names

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 Guidelines
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.




Braces
How to use the styles of braces
// Use in getter and setter functions in the header file.
int f() { return 42; }

// Use for while/for loop.
while(!dead) {
    eat();
}

// Use for class declarations and function declarations.
int X::f()
{
    return 42;
}

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.

Namespace smilegame
{
   void Le();
   ...
}   // smilegame


Classes
Access control
Make data members private and use accessor functions. A variable with the name _foo has the accessor function Foo() and SetFoo().

Access blocks
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)
  • Constructors
  • Destructors
  • Methods
  • Data members

C++ Features
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.



Comments
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 Guide
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.

///   @file
///  
///   This file contains classes to handle the smileys
///   in the game.

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.

///   Class to handle the yellow smileys in the game.
class YellowSmiley

Comment a function declaration
In the declaration (.h) describe the what a user need to know to call the function.

///   Kills the smiley and gibs him if enough damage.
float Die()

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.

int num_of_spawned_smileys;    ///< Total number of smileys spawned
/// Total number of evil smileys. Evil smileys are evil even after they are dead so
/// sooner or later the undead smileys will rule the world.

float num_of_evil_smileys;


Comments