CPP Style Guide

The styling conventions that we will be using are largely based off of the Google C++ Style Guide. When in doubt, consult that guide for clarification on things that are not in this style guide.

Comments

Each method should have an accompanying comment explaining its function, inputs, and output. Any side effects of the method should also be noted. In addition, each class should have a comment that describes the use cases of the class. For method and class comments you should use the

/**
 * ... comment ...
 */

commenting syntax.

Variable Scoping

Variables should be declared in the smallest scope that are possible for the variables. In addition, variables should be declared and initialized on the same line if possible. Global variables should be minimized as they can easily produce bugs in the code.

Structs

Whenever you have a data type whose only function is to store data, it is preferable to use a struct instead of a class. Using structs makes it more clear that the object does not have any additional methods and only stores data.

Function Modularity

Functions should be as short as possible, with each function performing a single, distinct task. If a function performs more than one task split the function into multiple functions. This keeps the code readable and maintainable.

Function Overloading

Overloading is preferable to using default arguments, so if you have a function that can take in different sets of parameters you should create a overloaded function for each parameter set. Default parameters can often lead to confusing logic which can be separated out into multiple functions.

Naming

Names of variables, functions, and classes should be optimized to be as clear as possible. Use of abbreviations and shorthand are acceptable in cases where their meaning is common knowledge, but if the longer versions are preferred. As far as casing goes, class and method names should use CamelCase while variable names should use snake_case.

TODOs

TODOs should be associated with a owner. The purpose of this is to maintain accountability for all accumulated technical debt, and to associate an owner with a future task.

If you need to add a TODO item to the codebase, please use the following structure, replacing the owner with your Github username. Note that this is enforced by the linter; you will not be allowed to merge code with a TODO that doesn't have an owner.

// TODO(LINKIWI): Handle the error return case
if (!doSomethingThatMightError()) {
  ...
}

Whenever possible, after you merge code with a TODO item, create a new issue describing the TODO item's resolution step(s), and assign it to TODO item's owner. This prevents TODOs in the codebase from spiraling out of control with no clear ownership.