69 lines
2.1 KiB
Markdown
69 lines
2.1 KiB
Markdown
# 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).
|
|
|
|
Put comments on their own lines.
|
|
Format comments to improve readability, don't have long single-line comments.
|
|
|
|
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 acronyms and/or
|
|
universally used.
|
|
|
|
Use explicitly sized data types where possible.
|
|
For example, use `int32_t` instead of `int`.
|
|
|
|
## 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.
|