bitshift/knowledge-base

Table of Contents

Programming Guidelines

git
Coding Style (C++)

Line Width
Indentation
Braces
Pointer and Reference Types
Names
Functions
Include Guards
Types
Formatting Tools

Coding Conventions (C++)

Terminology
Types
Error Handling
Memory Management

Coding Style (TypeScript)

Line Width
Indentation
Braces
Semicolons

Coding Conventions (TypeScript)

Programming Guidelines

git

One very important rule, the default git branch will always be master. master has never been a reference to the Slavery in the United States. The only people making that connection are the ones making that connection, no one else. It has never been and never will be a racist reference in the context of git.

Coding Style (C++)

This section presents the preferred coding style for C++ source code.

The coding style described in this section is subjective, but tries to be consistent and its purpose is to increase code legibility.

Line Width

Try your best to keep line widths shorter than 80 characters long.

It's assumed that most Bitshift developers do not use IDEs on widescreens, 80 column terminals running Vim are more likely to be used.

Indentation

Each new level is indented by 2 spaces, braces go on the line of the preceding statement, unless it's a function definition.

Namespace members are indented as well.

Do NOT ever use tab characters. They're evil.

Braces

Curly braces are used for all statement blocks, even single statements.

if (condition) {
    single_statement;
}

Pointer and Reference Types

The asterisk in pointer types and the ampersand in reference types should be aligned with the type.

int* int_ptr{};
int& int_ref = *int_ptr;

Names

All names in the code use snake_case. Member variables are prefixed with a leading underscore.

Functions

Functions should be declared by placing the returned value type on a separate line from the function name. If the parameters don't fit on a single line they should be split with the parameter names right aligned.

string
my_function()
{
    // ...
}

string
my_class::
my_function(my_first_type         arg_0,
            my_second_type const& arg_1)
{
    // ...
}

Include Guards

Use the full path of the file as the include guard using __ as a directory separator replacement.

Do not use #pragma once.

// path: seafire/protocol/grammar.hxx

#ifndef seafire__protocol__grammar_hxx_
#define seafire__protocol__grammar_hxx_

#endif

Types

Types should be written right-to-left, as they are read right-to-left.

std::string const my_string; // const string
int const* const my_int; // const pointer to const int

This is perfectly valid C++.

Formatting Tools

Do NOT ever use any tools such as ClangFormat or Prettier, they're either way too opinionated or impossible to configure exactly.

Formatting code manually in Vim is 100x faster than trying to shoehorn ClangFormat into formatting every comma correctly.

Coding Conventions (C++)

Terminology

Parameter

A parameter is the named parameter of a function.

void
my_function(char const* param); // param is a parameter

Argument

An argument is the value passed in a function call.

my_function("hello, world"); // "hello, world" is an argument

Types

Always used fixed width integers (int8_t, uint16_t, etc).
Only use char when explicitly dealing with characters.
Mark constructors as explicit unless implicit conversion is desired.

Error Handling

Use exceptions for exceptional error states (e.g. null pointers).
Use std::error_code& for expected error states (e.g. invalid user input).

Prefer an output parameter when using std::error_code& rather than a return value.

Memory Management

Prefer stack allocation.
Use unique_ptr or shared_ptr for heap objects.
Try your best not to use raw new and delete.

Coding Style (TypeScript)

Line Width

Try your best to keep line widths shorter than 80 characters long.

It's assumed that most Bitshift developers do not use IDEs on widescreens, 80 column terminals running Vim are more likely to be used.

Indentation

Each new level is indented by 2 spaces, braces go on the line of the preceding statement, unless it's a function definition.

Do NOT ever use tab characters. They're evil.

Braces

Curly braces are used for all statement blocks, even single statements.

if (condition) {
    single_statement;
}

Semicolons

Always terminate statements with semicolons, even if TypeScript allows omitting them.

Coding Conventions (TypeScript)

Always specify function return types.
Always specify function parameter types.

Quick Links