FOSS-VG/code_style.md

# Formatting Guidelines

This document lays out how to format code and documents as well as
a few coding practices.


## Markdown

Don't go beyond 80 characters per line, preferably slightly less.
This improves readability on a terminal.

Leave two empty lines between sections for the same reason.

Indent by two spaces.


## C++ / C++ headers

Include the copyright notice as present in the template at the top of
each file.

Don't use excessive comments, use descriptive names instead.
There is no such thing as too long names (within reason, of course).

Don't have comments that go beyond 80 characters per line, preferably
slightly less.

Put comments on their own lines.

Indent by four spaces.

Put opening curly braces used for scoping (namespaces, functions, conditions,
loops, etc.) on the same line as the code declaring the scope and the
corresponding closing curly braces on their own line indented the same
as the code declaring the scope.
(Java-style... How do I reword this properly?)

Put a line break after `template <typename T>`.

Use camel case names where possible except for constants which should use
all uppercase letters and underscores for their names.
Variables and functions start with a lowercase letter, classes and structs
with an uppercase letter.

Avoid abbreviations unless they are well known and universally used acronyms.

Use explicitly sized data types where possible.
For example, use `int32_t` instead of `int`.

When coming up with names, refer to data types by category and size.
For example, refer to double precision floating point numbers as `float64`
instead of `double`.


## Shell Script

Use the hash bang `#!/usr/bin/env bash`.

Include the copyright notice as present in the template below the hash bang.

Indent by four spaces.

Don't have comments that go beyond 80 characters per line, preferably
slightly less.

Put special commands like `then` and `do` on the same line as the control
structure they belong to. Use the same indent for special commands like
`fi` and `done` as for the control structure they belong to.

Use uppercase variable names with underscores except for loops where
lowercase variable names with underscores may be used for counters and
iterators.

Be verbose about every step that is being taken.