diff --git a/code_style.md b/code_style.md new file mode 100644 index 0000000..645d94e --- /dev/null +++ b/code_style.md @@ -0,0 +1,70 @@ +# 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 `. + +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. + +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. +