Skip to content

Code Style

Jump to bottom
Mark Vousden edited this page Jan 15, 2019 · 5 revisions

This page outlines the code style for C++ source used in the Orchestrator. Each line consists of a "rule number", a rule content, and an example if appropriate. To propose a change to the style, open an issue in the Orchestrator issue tracker.

Note that these style guidelines are fundamentally guidelines. Reviewers can choose to block your pull request on the basis of style, but we are (mostly) humans. Be civil in your enforcement of this style if you are a reviewer, for impolite behaviour has a nasty way of coming back to its progenitor :).

This style guide is based on the style guide defined by Porter Scobey in the further reading section.

0: Do not compromise code readability in favour of this style guide. Use your judgement and be reasonable.

Naming

1-0: Non-boolean variables and value-returning functions and methods (like property-getters) must be Camel-case nouns.

1-1: Boolean variables must be Camel-case adjectives, e.g.:

bool burned;
bool filled;
bool edible;
bool valid;

1-2: Boolean functions should be based on the adjectives they describe, in Camel-case, e.g.:

bool isBurned();

1-3: Void functions must begin with a verb; non-void methods may also begin with a verb (relevant in the case of getters), e.g.:

void GetLastPie();
mailbox* board.setMailbox();
int carrots = farm.getNumberOfCarrots();

1-4: Constants must be upper-case with words separated using underscores, e.g.:

const int SIZE = 100;
const double PARTICLE_VELOCITY = 0.25;

1-5: Variables defined in pre-processor directives must be upper-case with words separated using underscores, e.g.:

#define FOUR 4

1-6: Functions must be Camel-case, except for free void functions, which must start with a capital letter, e.g.:

void Display();
int main();

1-7: Classes must be Camel-case starting with a capital letter, and must be nouns, e.g.:

Box
Board
UserCommand

Indentation and Alignment

2-0: Indent with spaces, using multiples of four only. Use of indentation should not inhibit readability.

2-1: The following items must exist at one greater level of indentation to their surrounding statements:

  • Statements in the body of a function (method or free), loop, or conditional block. Single-statement conditional blocks can be defined without curly braces for readability.

  • Member definitions of classes or structs (use classes).

2-2: Enclosing braces on different lines must be aligned vertically, e.g.:

void PointlessFreeFunction()
{
    return;
}

2-3: Non-inline comments (see 4-0) must have the same indentation as its context (and should be spatially local).

2-4: Regarding statements that are broken over multiple lines that are too long (see 6-1), indent each line following the first by one level.

Whitespace

3-0: The linefeed character (ASCII 10), and only this character must be used to break a line. The carriage return character (ASCII 13) must not be used.

3-1: One line of vertical whitespace must be used to separate function definitions and class definitions. For readability, conditional blocks, case statements, loops, and other statements may be separated for readability.

3-2: Horizontal whitespace must be used to separate non-unary operators, with exception to predicates and loop initialiser statements, for which they should be omitted.

Comments

4-0: C-Style comments (/* Comment */) should be used over C++-style comments (// Comment\n) for comments that span multiple lines.

4-1: Files should contain header documentation, which opens with a terse description of the source in that file, and includes a more verbose description, referring to documentation where appropriate.

4-2: A class should contain header documentation comments, indented on the same level, and prior to, its definition. These comments must define what the class is for, e.g.:

/* Shoes that can be used by something that needs to run.
 * 
 * Defines various properties used by the owner of the shoes to enable them to
 * run at particular speeds.
 * 
 * Example:
 * 
 *  Person person;
 *  RunningShoes shoes;
 *  person.wear(shoes); */
class RunningShoes
{
    ...
}

4-3: Functions, like classes, should contain header documentation comments, indented on the same level, and prior to, its definition. These comments must define:

  • A terse description of the function, first.

  • A more verbose description of what the function does.

  • Conditions on which the function must operate, and the conditions it imposes on the system after its operation (if any).

  • The meaning of the return value of the function, if any.

  • The meaning of each of the function's parameters, if any, in order.

  • Exceptions it is expected to throw, if any.

Do not state the completely-obvious. The simplest, most elegant functions may not require a documentation comment. If the function is overriding, focus on the override instead of repeating the definition from the overrided function.

Source File Structure

5-0: Files should be structured in the following sequence, with other components weaved in as needed:

  • Header guards if the file is a header file.

  • File documentation comments.

  • Pre-processor directive includes (header files must include all function prototypes).

  • Defined global constants and data types.

  • The entry point (main), if appropriate.

  • Further free function and class definitions. Also includes declarations if the file is a header file.

Miscellaneous

6-0: Source files must be encoded using ASCII.

6-1: Lines must not exceed 79 characters in length.

6-2: Different statements must be on different lines.

6-3: All English words must be spelled correctly under British English.

Further Reading

Clone this wiki locally