Style Guide

Style guide should be followed for all C++ code developed for WARG.

Spacing

We use 4 spaces instead of tabs here.

Variables

Note: For class and struct member conventions, refer to the Data Structures section.

All variables must follow snake case.

int you_are_reading_this = 0;
int you_are_reading_this{0};
bool nice_thanks_for_reading = false;
bool nice_thanks_for_reading{false}; 
double this_is_super_fun = 0.0f;

As a rule of thumb, all variables should be initialized upon declaration to prevent undefined behaviour.

Only exception to this is static variables in classes, which should have an underscore before the first character:

// These are static variables for a class
static int _you_are_reading_this{0};
static bool _nice_thanks_for_reading = false;
static double _this_is_super_fun = 0.0f;

File-Scope Global Variables

Should always be static and named like static class member variables:

static int _i_am_a_static_integer = 0;

Constants

Constants (const and constexpr) should be named using camel case, with the first character being a k:

const int kYouAreReadingThis{0}
constexpr bool kNiceThanksForReading{false};

Pointers

The* should be attached to the variable:

int *integer_pointer = nullptr;

As a rule of thumb, all pointers must be initialized on declaration. If you are not assigning it a value, then set it to nullptr like the example above.

Declaring Variables on the Same Line

Declaring and initializing multiple variables of the same type can be done on the same line. However, the number of variables on the line should not exceed 5:

int a = 0, b = 1, c = 2, d = 3;

int a = 0, b = 1, c = 2, d = 3, e = 4, f = 6; // Not good, six variables on same line

Structs and Classes

When declaring structs, classes, or any object for that matter, we will prefer to use C++'s implementation of value initialization so all parameters are default initialized (are given their default value).

struct A {
... 
};

int main() {
  A hello {}; // The curly brackets trigger value initialiation
}

Mathematics

Mathematical Operations

There should always be spaces around all mathematical operators. There should always be spaces between equal signs.

int b = (1 + 2 - 3) * random_variable / 5.0 + random_variable_two % 7;

Selection

Conditions

Operations

There must be a space around all operations (==, >=, &&, etc.)

if (1 < 2 || (1 <= 3 && 2 >= 1) || 1 == 1 || 1 > 0) { ... }

Additionally, if a condition list has more than one condition, any condition containing mathematical operations must be surrounded in brackets:

if (1 + 1 > 0) { ... } // Only one condition

if ((1 + 1 > 0) && 4 == 4) { ... } // More than one condition

Order of Terms

When comparing the value of a variable, it is best practice to put the value before the variable identifier. This prevents runtime errors from occuring in case you use = instead of ==.

if (1 == a) { ... }

If Statements

Structure

There must be a space around the if and else keywords, and there must be a space separating the condition list and the opening curlly-bracket. Curly-brackets must be on the same line as the condition list.

if (a == b) {

} else if (b == c) {

} else {

}

Always use curly brackets, even if the code within the if statement is one line.

Ternary Expressions

Pretty standard.

bool b = true;
int a = b ? 1 : 0;

Switch Statements

Switch statements are pretty standard too, just need to get the indentation right. Also, ensure you put breaks in every condition unless you cannot put it:

int a = 1;
switch(a) {
  case 1: // Indent the cases 
    ... 
    break;
            // Keep a space between the end of one case and the condition of the next 
  case 2:
  case 3:
    ... 
    break;
    
  default: // Always include a default case
    break;
}

Loops

Curly Brackets

Should be on the same line as the do, for, and while keyword:

for ( ... ) {
}

do {
} while ( ... );

while {
}

Also keep a space between the do, for, and while keyword; conditions, and open curly-bracket.

Conditions follow same rules as if statements.

Breaks

We try to avoid using the break keyword when exiting loops. Instead, use a boolean flag to track if the loop is done executing.

bool isDone{false};
for (int i = 0; i < 10 && !isDone; i++) {
  if (6 == i) {
    isDone = true;
  }
}

continue statements will be allowed, however they should only be used if it will simplify the code by a significant amount.

Functions

Naming and Brackets

Functions should use lower camel case in their names. There should be no spaces between the function name and the parameter list. The open curly-bracket must be on the same line as the function name, and must be separated from the parameter list by one space:

int hewwoThereFwend() { 
  return 0; 
}

Parameters

Parameter names

Parameter names should follow the same conventions as written in the Variables section.

Pointers

The* in pointers must be separated on both sides by one space.

void hewwoThereFwend(string * fwend_name) { ... }

NOTE: Moving forward, we will prefer to use reference parameters over pointers when passing by reference. It is a more C++ style of programming.

Reference Parameters

The & in reference parameters must be appended to the datatype of the parameter.

void hewwoThereFwend(string& fwend_name) { ... }

We will prefer to use this C++ feature when passing values by reference. To learn more about reference parameters, you can refer to the following links:

More than one Parameter

Parameters in a list must be separated by commas (obviously lol), but a space must separate a comma and a parameter:

void switchFwendName(string& fwend_name, string new_fwend_name) { ... }

If the parameter list is very long, creating a vertical list of parameters is acceptable too. Just ensure each parameter starts in the same column so as to ensure readability.

void hewwoThereFwend(string fwend_one,
                     string fwend_two,
                     string fwend_three,
                     string fwend_four,
                     string fwend_five) { ... }

Commenting

All function declarations must have a comment above describing its purpose, parameters, and returned value. Pay notice to the spacing on the* and the /** that opens the comment

/**
* This function switches the friend's name with a new name
 *
* @param fwend_name -> reference pointing to the friend's name
* @param new_fwend_name -> value of the friend's new name
 *
* @return none
 */
void switchFwendName(string& fwend_name, string new_fwend_name);

Data Structures

Classes

Classes use PascalCase. Public member variables and methods will be declared first, followed by protected and then private:

class ExampleClass {
  public:
    ... 
  
  protected: 
    ...
    
  private:
    ...
};

Member Variables

Non-static member variables should use snake case.

Constants should use camel case with a k as the first character.

Static variables should use snake case, but have a _ as the first character.

class ExampleClass {
  public:
  private:
    // Member variables should always be private. If you need access to them, provide getters and setters.
    int hello_there; 
    const double kGeneralKenobi; 
    static int _its_over_anakin;
};

// Remember static variables must be redeclared outside of the class declaration
int ExampleClass::_its_over_anakin {0};

Constructors

We prefer to use initializer lists when initializing member variables, however there are cases where we should stick to initializing member variables within the constructor.

class ExampleClass {
  public:
    ExampleClass();
    ExampleClass(int num_apple_pies);
  
  private:
    int apple_pies, banana_pies;
    double slices_left;
}

ExampleClass::ExampleClass() : apple_pie {0}, banana_pies {0}, slices_left {0.0f} {}

// You can stack your initializing list. Just make sure they start in the same column
ExampleClass::ExampleClass(int num_apple_pies) : apple_pies {num_apple_pies},
                                                 banana_pies {0} {
  slices_left = 6* num_apple_pies; // If an operation is required, preferred if initialization is within constructor
}

Initializing Classes

When statically declaring a struct, you should initialize it immediately. If a default constructor exists, call that, else call another constructor.

class ExampleClass {
  public:
    ExampleClass();
    ExampleClass(int num_apple_pies);
  
  private:
    int apple_pies, banana_pies;
    double slices_left;
}

int main() {
  ExampleClass default_class {}; // Preferred over `ExampleClass class_with_apples()`
  ExampleClass class_with_apples {1}; // Preferred over `ExampleClass class_with_apples(1)`
}

If declaring a class pointer, initialize to nullptr if no other options exist:

class ExampleClass {
  ...
};

int main() {
  ExampleClass* example_pointer = nullptr; // Good!
  
  ExampleClass statically_declared_class {};
  
  ExampleClass* other_pointer = &statically_declared_class; // Also good!
  
  ExampleClass* one_more_pointer = functionThatReturnsAClassPointer(); // Good too!
}

Structs

Structs should only be used to store Plain Old Data (POD). That means no methods should ever be declared in a struct. If you need method, use a class :))

Structs will use PascalCase for their names. We will use the following syntax:

struct StructName {
  ...
};

Initializing Structs

When statically declaring a struct variable, always initialize upon declaration:

StructName struct_variable {}; // Value initialization

When declaring a struct variable pointer, initialize it to nullptr if no other options exist:

StructName* struct_variable = nullptr;

StructName* struct_variable_two = functionThatReturnsAStructNamePointer(); // Valid too!

Enums

We use PascalCase for enunms, and the constants will use all caps with underscores separating words. Additionally, the first constant should have a = 0 appended to it.

enum EnumOne {HEWWO = 0, THERE, MY, FWEND};

 // If there are a lot of terms, you can split them on multiple lines with one constant per line
enum EnumTwo {
  HEWWO = 0,
  THERE,
  MY,
  FWEND,
  YOU,
  AWRE,
  AMAZING
};

Style Guide

Spacing

Variables

File-Scope Global Variables

Constants

Pointers

Declaring Variables on the Same Line

Structs and Classes

Mathematics

Mathematical Operations

Selection

Conditions

Operations

Order of Terms

If Statements

Structure

Ternary Expressions

Switch Statements

Loops

Curly Brackets

Breaks

Functions

Naming and Brackets

Parameters

Parameter names

Pointers

Reference Parameters

More than one Parameter

Commenting

Data Structures

Classes

Member Variables

Constructors

Initializing Classes

Structs

Initializing Structs

Enums

Further reading