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).

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.