CPP Standards - dylondark/cob-taylor-games GitHub Wiki

Syntax

• Curly brackets on separate lines (Allman style).
• Indentation with 4 spaces (Qt Creator default).
• Parameters in functions should always be passed as const reference rather than by value, unless they are basic types like int or double (std::string is not a basic type).
• No compiler warnings.
• Don't use curly brackets in if statements and loops that are only one line.
• "using namespace std" is not okay, but using std::string or any other object within a namespace is fine as long as there are no conflicts.
• Single empty lines separating blocks. This includes:
  • Blocks of code
  • Blocks of include statements
  • Blocks of using statements
  • Blocks of pragma statements (statements that start with # other than include statements, like #ifndef, #define, etc)
• Single empty lines separating function declarations and definitions.
• Code lines that have a singular purpose within functions should be separated into chunks (separated by lines).
• Functions that have similar purposes should be grouped together (for example: on_lbGame1_pressed(), on_lb_Game2_pressed(), etc. should be placed next to each other).
• Functions that are numbered should be in order (for example: on_lbGame2_pressed() should come after on_lbGame1_pressed()).
• Parameters in function definitions should be named, and they should be the same names as in the definition.
• Line comments should start with a space unless they are used for commenting out code.
  • // this is a comment, it starts with a single space
  • //cout << "this is code, it starts with no spaces";

/*
    Block comments should look like this.
*/

• No unnecessary newlines (newlines at the beginning and end of functions, more than one empty line separating anything, etc).
• Don't use auto type for basic types like int and double.
• Initializer lists in constructors should be on their own line.
• Lines of code should only be one line of text (not split between separate text lines), except in cases where there are long parameter lists.
• In class declarations, the order of member declarations should be constants, then variables, then functions.
• Declare pointers with the asterisk on the type name (where possible). For example: int* ptr rather than int *ptr.

Naming

• Use camelCase (first word lowercase, all other words capitalized, no underscores) for function and variable names.
• Use PascalCase (first letter of every word capitalized, no underscores) for class names.
• Constants should be all caps with underscores for spaces (for example LOOP_SECONDS is a constant, while loopSeconds is a variable).
• File names should be all lowercase and should be the same as the class or namespace within them (for example, class "TriviaController" will have files "triviacontroller.h" and "triviacontroller.cpp", and namespace Utilities will have "utilities.h" and "utilities.cpp").

Comments & Documentation

• All block comments and comments documenting functions or class member variables should have proper grammar and punctuation.
• All .h and .cpp files should have a block comment at the top with the filename and short description of the file.
• All functions should be documented with block comments containing description of function followed by description of parameters and return value if applicable, in both the h and cpp files.

/*
    Setter for frameInterval.
    This MUST be used to set the same interval value as the timer that is connected to this object.
    TODO: Find a better way to enforce frameInterval being set to the same value as the interval of the timer connected to this object.

    int ms: Milliseconds value to set
    return int: Status code indicating 0 for success and 1 for failure.
*/
int setFrameInterval(int ms);

• Variables in class declarations should have a line comment preceding them (or a block comment if there is a lot to explain).
• Chunks of code should have comments preceding them.
• Classes should have a block comment preceding them (in the header file) explaining what the class is for and any other important information about it.
• Any comments containing TODO messages should have TODO: in them.