2.2 KiB
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.