Ilmendur - Heirs to the Elven Sword

# Coding Styleguide

Those who have worked on the TSC project will remember the dreaded discussion about coding style. This project will avoid the trap by using a consistent coding style right from the start. It is outlined in this document.

The game's source code is formatted according to the [1TBS](https://en.wikipedia.org/wiki/Indentation_style#Variant:_1TBS_(OTBS)) style, which is a variant of K&R, with slight adjustments. Details are documented below.

In general, try to keep your code readable. Specifically, it is often useful to leave empty lines to separate logically grouped statements from one another.

## Indentation, line length

Source code is indented with 4 spaces, tabs are not used. Lines should be broken around 80 characters, and the resulting continuation lines should be indented so that it makes sense to look at. Example:

~~~~~ c++

if (somecondition) {

    thisIsAVeryLongFunctionName(this_is_a_parameter,

                                this_is_another_parameter,

                                third_parameter);

}

~~~~~

## Commentary

Semantically, comments should normally reflect why code is written the way it is. Normally it is not required to explain what code does, unless it is an exceptionally complex part. Syntactically, use `//` for one and two lines of comments. Starting with the third line, comments should use the bock syntax `/* ... */`. In the block syntax, align each star with the one on the preceeding line. Terminate the comment block on the last line of the comment.

~~~~~ c++

// Careful: this is used in foobar() as well

/* This code is designed to specifically fit the purpose of an example.

 * It was not at all easy to come up with all this text, but for the

 * sake of an example, it was required to do so. */

~~~~~

### Documentation comments

Where Doxygen is used to generate documentation, use Doxygen's `///` markers for short and the `/**` markers for long documentation. Other than that, the above advice applies.

## Case of identifiers

* Macros are ALL_IN_CAPS.

* Structure and class identifiers use CamelCase.

* Member function identifiers are CamelCase as well.

* Member variables are snake_case. This includes static member variables, even if they are constant.

* Local variables use snake_case.

## Abbreviated Hungarian Notation

Identifiers of variables and constants begin with a short sequence of characters that encodes some important information about the variable in question. This is called [Hungarian Notation](https://en.wikipedia.org/wiki/Hungarian_notation), but in full, it is cumbersome to read and leads to long identifier names. The following prefix characters have been chosen with respect to two goals: Make variable scope immediately visible, and warn of "unusual" types.

| Prefix | Meaning                                                          |

|--------+------------------------------------------------------------------|

|        | No prefix: Local variable                                        |

| m      | Member variable                                                  |

| s      | File-local variable                                              |

| g      | Global variable                                                  |

| p      | Variable holds a pointer (both raw and managed pointers)         |

| a      | Variable holds a raw array (not: vector or other C++ containers) |

The scope prefix comes before the type prefix. Thus, `mp_foo` is a member variable holding a pointer, and `ga_argv` is a global variable holding a raw C array.

## Compound Statements

The opening brace resides on the same line as the statement it applies to, regardless of whether this is a function, a control flow statement, or a class or enum declaration. The closing brace has a line on its own to ensure it is easily spottable where a block ends.

~~~~~~~~~~~ c++

class Foo {

};

if (condition) {

    // ...

}

while (condition) {

    // ...

}

void main() {

    // ...

}

~~~~~~~~~~~

The rare case of a terminal `while` has the `while` after the closing brace on the same line.

~~~~~~ c++

{

    // ...

} while (condition)

~~~~~~~

## Brace Cuddling

In an if/elsif/else statement, braces are cuddled to keep code compact.

~~~~~~~~~~ c++

if (condition1) {

    // ...

} else if (condition2) {

    // ...

} else {

    // ...

}

~~~~~~~~~~~

## Braces around short statements

It is okay to leave breaces out for one-line `if`, `while`, etc. statements. If the surrounding code grows sufficiently complex so that the entirety of such a statement cannot be determined with a single look (e.g. long `else` conditional), use braces even in those parts where the syntax allows to leave the braces out. It helps clarity in that case.

~~~~~~~~~ c++

// Short: good

if (condition)

    doit();

// Longer, but still okay

if (condition1)

    doit();

else

    doother();

// This is too complex, use braces everywhere to clarify

if (condition1) {

    doit();

} else {

    doother1();

    if (condition2) {

        something();

    }

    else {

        andmore();

    }

}

~~~~~~~~~

## Parantheses and spacing

Between a keyword and the opening paranthesis is exactly one space. Between the closing paranthesis and the opening curly brace is exactly one space as well. *There is no space between a function name and the opening paranthesis of its argument list*, neither in declaration nor in calling of a function.

~~~~~~~~ c++

void foo() { // No space between function name and (, but one space between ) and {

    if (condition) { // One space between keyword if and (, and one space between ) and {

        // ...

    }

}

~~~~~~~~