SLProject Coding Style

If you are a contributor to the SLProject please follow the following coding style:

Naming Convention within lib-SLProject and lib-SLMath

• Everything is in English (names, comments just everything!)
• Data type names (classes, structs, typedefs & enums) begin with a big SL
  • All classes that contain OpenGL code begin with SLGL
  • All classes that contain OpenCV code begin with SLCV
• Class headers are within a file of the same name with the extension .h
• Class implementations are within a file of the same name with the extension .cpp
• Method and variable names begin with a small letter
• Private members variables begin with an underscore (e.g.: _sceneViewCamera)
  • Setters have the same name as the member variable without the underscore
  • Getters have the same name as the member variable without the underscore
• All names use camel case (e.g.: camelCase(), SLSceneView)
• All classes should use initialization lists for non-basic types to increase efficiency
• Pointer and reference symbols are always on the left (Type* ptr, Type& ref)
• When declaring multiple pointers or references always use a new line per variable. Don't do this: Type* ptr, *ptr2, *ptr2;
• If a variable has a unit append it to the variable name (angleRAD, angleDEG, speedKMH)
• Try to use short names for variables that are used very often.
• Do NOT use using namespace std;. Use e.g. using std::string; for often used std datatypes.
• Basic types are redefined with typedefs in SL.h (SLint for int etc.)
• Standard containers typedefed and begin with:
  • SLV: typedef std::vector<SLMesh*> SLVMesh;
  • SLL: typedef std::list<SLMesh*> SLLMesh;
  • SLM: typedef std::map<int, SLMesh*> SLMMesh;
  • SLQ: typedef std::queue<SLMesh*> SLQMesh;
• Enumerations are defined in SLEnum.h and have the following pattern:

//! Mouse button codes
enum SLMouseButton
{   
    MB_none,
    MB_left,
    MB_middle,
    MB_right
};

Automatic Formatting with clang-format

• The following Formatting Rules can be automatically applied with the clang-format tool. It allows powerful formatting and saves a lot of time during coding. Applied on a keyboard shortcut, on saving or even on a git commit makes a consistent code style possible.
• The options for the Formatting Rules are defined in the file .clang-format in the SLProject root directory. Please do not change this file without contacting [email protected]. See the documentation about the clang-format options for more information.
• clang-format can be integrated into almost any IDE: Qt Creator, Visual Studio, XCode and Android Studio.
• On Mac or Linux clang-format must be installed with a package manager (on mac with brew install clang-format)

Formatting Rules

• IDENTIFICATION: 4 SPACES, NO TAB SIGNS
• BRACES: IN FRONT OF THE BLOCK
• First line: On the next line of the opening brace
• Parameters: No space after ( and before ).
• One space after keywords (if, for, do, while, switch, ...)
• One space before and after all types of operators
• Code Width:
  • Try to be no longer than around 80 characters. Clang-Format does not enforce this to allow exceptions.
  • Short code after if, for or while can be on the same line.
  • If code doesn't fit within 80 characters just break the second parameter. clang-format does the automatic alignment for you:

void SLExampleClass::exampleMethod(SLint     index, 
                                   SLfloat   speedKMH, 
                                   SLCamera* camera)
{	
    // Float array with vertex X & Y of corners
    SLVVec2f P = {{0.0f, (SLfloat)_resY},
                  {0.0f, 0.0f},
                  {(SLfloat)_resX, (SLfloat)_resY},
                  {(SLfloat)_resX, 0.0f}};
}

• In special cases you can turn off/on clang-format:

    // clang-format off
    SLMat4f      SLM(M->a1, M->a2, M->a3, M->a4,
                     M->b1, M->b2, M->b3, M->b4,
                     M->c1, M->c2, M->c3, M->c4,
                     M->d1, M->d2, M->d3, M->d4);
    // clang-format on

Commenting

• Comment as much as necessary.
• There must be an empty line before a single line comment.
• We use the Doxygen tool for the source code documentation.
• Comment code objects (classes, structs, members & methods) with Doxygen tags:
  • The short comment tag before a code object is //!
  • The short comment tag behind a code object is //!<
  • The long comment tag is /*< ... */
  • Comment a class with a short AND a long comment in the header file
  • Comment all member variables with a short comment behind the member in the header file
  • Comment all methods with a short and/or long comment in the implementation file

//! The SLExampleClass is just an example for commenting.
/*! This example class serves as an example how we use the Doxygen tags
to comment the different code objects. Classes must use always have a short
and a long comment.
*/
class SLExampleClass
{
    public:
    void exampleMethode (int index);

    private:
    int _index;   //!< The index is an example member

}

//! The exampleMethod is just an example with a short comment
void SLExampleClass::exampleMethod(SLint index)
{	
    _index = index;
}

Header files

• Add an include guard right behind the file header
• A header file should have everything it needs to compile by itself:
  • Put the corresponding header file in a test.cpp with no other includes to check if it compiles on its own
  • Forward declare where possible
  • Reduce includes to a minimum