= Style Guide for Orxonox C++ Code =

'Coding style' refers to the way source code is formatted. For C++, this involves things like brace placement, indentation, and the way parentheses are used. The most important thing is for the code to be consistent within a program or library - code with sloppy formatting is not acceptable, since it is hard to read.

When writing a new program or library, please follow a consistent style of brace placement and indentation. We recommend the following code style.

Remember that any violation to the guide of course is allowed if it enhances readability.

== File Organization ==
=== Header and Source ===
Keep your classes/files short, don't exceed 2000 LOC (if it get's longer you may separate functions into different modules). Put every class in a separate file and name the file like the class name (don't use !CamelCase names separate them with underlines). Create a separate header (ends with .h) and source file (ends with .cc). Example for class {{{MyExampleClass}}}.
{{{
file names:
my_example_class.cc
my_example_class.h
}}}

=== Namespaces ===
Create a directory for every namespace (== create a directory for every modules and all its submodules).

=== Inlineing and Templates ===
Inline functions and template structures should be declared in a .h header file as described above but implemented in a *-inl.h file (since templates are normally not implemented in a source .cc file).

=== Machine-Dependent Code ===
Place machine-dependent code in a special file so that it may be easily located when porting code from one machine to another.

== Comments ==

=== Introductory Comment ===
Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents:
{{{
// 
}}}

== Naming Conventions ==
=== Classes and Types ===
Names representing types must be in mixed case starting with upper case.
{{{
class SavingsAccount {
};

struct SimpleStruct {
};
}}}

=== Variables ===
Variable names must be in mixed case starting with lower case.
{{{
string testString;
int numberOfTimes;
}}}
Memeber variables of classes all end with an underline:
{{{
class TestClass {

private:
  int numberOfTimes_;
};


=== Constants ==
Named constants (including enumeration values) must be all uppercase using underscore to separate words. Always use constants instead of numbers.
{{{
const int MAX_ITERATIONS = 5;

for (int i = 0; i < MAX_ITERATIONS; i++) {} // Instead of (... i < 5; ...)
}}}

=== Functions ===
Names representing methods or functions must be verbs and written in mixed case starting with lower case.
{{{
void calculateTheLowerBoundary() {}
int howManyItemsLeft() {}
}}}
For interface functions to local member variables use short functions:
{{{
class WorldEntity {
public:
  inline string Name() {
    return name_;
  }

  inline void setName(const string& name) {
    name_ = name;
  }

private:
  string name_;
};
}}}



== Indentation ==
=== Spaces ===
Use 2 spaces for an indentation level. Never use tabs, as it is common in windows IDEs.

== Special Implementations ==
=== Use STL Libraries ===
Use STL (standard template library) implementations of common abstract data structures like lists, arrays, stacks, queues, never implement your own!

== General Topics ==
 * different build targets possible (for subprojects)
 * different make options (make-dbg, make-opt)
 * unit test supported (in debug mode)
 * compiler mode: warnings being treated as errors

== Code Reviews ==
Code review is a pretty simple process: at its heart, it is little more than reading some code written by someone else. Nevertheless, it can be useful to have a set of things on which to focus during a review:

    * Does the branch merge or the diff apply cleanly?
    * Are there unit tests for the code being changed or added?
    * Do the unit tests pass for you?
    * Do the unit tests pass for buildbot?
    * Is there documentation for new code?
    * Where appropriate, has existing documentation been updated (including ChangeLog?/NEWS files)?
    * Does the code adhere to the coding standard? 

There's the easy list. Most are mechanical checks. Don't feel bad about rejecting a branch if the answer to any of these questions is no: the problems may seem minor in isolation, but each contributes to overall poor code quality. Moreover, sometimes apparently minor problems can be hiding larger issues.