Coding Style (CPP)

Coding Style (C++)

The C++ code in this project follows the following standard.

Naming Conventions

• All variables (arguments), namespaces, functions (methods) and files should be in camelCase. Classes should be in PascalCase.

• Names may contain ONE underscore (_) at the beginning or the end of the name, in order to diffrentiate from the keywords or other variables in the parent scope.

• Good:

class MyClass
{
    int myVariable = 0;

    void myFunction(
        int myArgumentA,
        int myArgumentB_,
        int _myArgumentC
    );
};

• Bad:

class my_class // Not PascalCase.
{
    int my_variable = 0; // Not camelCase.

    void my_function(
        int my_argument_a, // Not camelCase.
        int my_argument_b, // Not camelCase.
        int __my_argument_c // Not camelCase, and two underscores.
    );
};

Indentation

• Use 4 spaces for indentation. Do NOT use tabs.

• Good:

void myFunction()
{
    if (true)
    {
        // Do something.
    }
}

• Bad:

void myFunction()
{
  // Not indented properly.
  if (true)
    {
    // Do something.
    }
}

Braces

• Braces should be on the next line of the statement, and should NOT be on the same line.
• Braces should NOT be indented.

Tip

• Single-line statements need not have braces. Most formatters will get rid of them anyway.
• Indent single-line statements for differentiation.

• Good:

void myFunction()
{
    if (true)
    {
        // Do something.
    }
}

• Good:

void myFunction()
{
    if (true)
        doSomething();
}

• Bad:

void myFunction() {
    if (true) { // Braces on the same line.
        // Do something.
    }
}

• Bad:

void myFunction()
{
    if (true)
        {
        // Braces indented.
        }
}

Comments

• Both single-line (//) and multi-line (/* */) comments are allowed. There is not a strict rule for this.

• Use English for comments. Be clear and concise with the wording.

• Add ONE space before the comment delimiter (//), if it is a single-line comment, and after it.

• Good:

// This is a single-line comment.

/*
 * This is a multi-line comment.
 */

int main()
{
    doSomething(); // This is a in-line comment.
}

• Bad:

//This is a single-line comment.

/*
This is a multi-line comment. There is no space after the delimiter, or at the beginning.
*/

int main()
{
    doSomething();//This is a single-line comment.
}

Header Guards

• Use #pragma once for header guards. Do not #define macros for this.

• Good:

#pragma once

class MyClass
{
    // Class definition.
};

• Bad:

#ifndef MY_CLASS_H
#define MY_CLASS_H

class MyClass
{
    // Class definition.
};

#endif

Namespaces

• Use namespaces to group related classes and functions.

• Put everything, except the main function, in a namespace.

• Add a comment to the end of the namespace.

• Example:

namespace steppable::__internals::arithmetic
{
    class MyClass
    {
        // Class definition.
    }

    void myFunction()
    {
        // Function definition.
    }
} // namespace steppable::__internals::arithmetic

Important

For the time being, put everything into the steppable::__internals::arithmetic namespace.

Using the STL

You can use features from the C++ 23 standard. Although the old functions are more compatible, you are encouraged to use the more modern features.

util.hpp also provides a range of functions. See API Reference for more information.

Caution

Do NOT write using namespace std; in the code. Doing so makes it easy to override the standard functions.

Some Steppable functions may have the same names as the STL functions, but they take in strings instead. using namespace std; will cause confusion and errors while compiling.

Note

• It is fine to write using namespace with anything inside std or steppable, but not std or steppable itself.
• The statement namespace a = b; is fine as well, as long as a is not std or anything starting with steppable.

Good:

#include <iostream>

using std::cout;

namespace a = b;

int main()
{
    cout << a::myFunction();
}

Bad:

#include <iostream>

using namespace std;

namespace steppable
{
    int main()
    {
        cout << myFunction();
    }
}

Spacing

• Always put a space after a comma.

• Always put a space before and after an operator.

• Always put a space after a bracket if you are creating any sort of list (e.g., initializing an array or initializer list).

• Good:

int myFunction(int myArgumentA, int myArgumentB)
{
    int myArray[] = { 1, 2, 3 };
    int myVariable = myArgumentA + myArgumentB;
}

• Bad:

int myFunction(int myArgumentA,int myArgumentB)
{
    int myArray[] = {1,2,3};
    int myVariable = myArgumentA+myArgumentB;
}

File Structure

• Each file should be structured as follows:

  1. License header.
  2. Header guards.
  3. Include statements.
  4. Using statements.
  5. Namespace.
     1. Variables / constants / pointers.
     2. Class / struct / union definitions
     3. Function definitions

• The order of the elements in the file should be as follows:

  1. Public members.
  2. Protected members.
  3. Private members.

---

Tip

Tools that can help

If you are still confused by these rules, the following tools may help you make the code comply with them automatically.

• ClangFormat can help you format your code according to the standards. There is a .clang-format file in the project root directory, which you can use to format your code.

  To format your code, you can use the following command:

  clang-format -i <file>

• add_copyright_header.py is a Python script that can add a header to your files. You can use this script to add headers to your files instead of adding them manually.

  To use the script, you can use the following command (you need to have Python 3 installed on your system):

  python3 add_copyright_header.py <file>