Mercurial > vanilla
diff STYLE.md @ 31:afb6f8eb89da
vanilla: add more documentation
author | David Demelier <markand@malikania.fr> |
---|---|
date | Tue, 26 Feb 2019 09:16:42 +0100 |
parents | |
children | 3cffdd760a86 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/STYLE.md Tue Feb 26 09:16:42 2019 +0100 @@ -0,0 +1,162 @@ +vanilla CODING STYLE +==================== + +File content +============ + +- Use UTF-8 charset, +- Use Unix line endings, +- Never write two blank consecutives blank lines. + +Indent +====== + +Use tabs to indent and spaces for alignment. Tabs are meant and designed for +indenting code and have the advantage of being configurable. On the other hand +to keep code clean, you must align content with spaces only *within* a line. + +Note: we recommend 8 columns to avoid high number of indentations. + +Shell +===== + +In shell programming try to stick with POSIX shell whenever possible. Otherwise, +set the shebang to a different shell. + +Style +----- + +- Try to keep lines shorter than 80 columns + +Functions +--------- + +Don't use `function` keyword, just keep the function name. + +```sh +usage() +{ +} +``` + +It's usually recommended to prefix functions names with the program name to +avoid collisions with global commands. + +```sh +foo_clean() +{ +} + +foo_process() +{ +} +``` + +Options +------- + +For options, use `getopts` and prefer short options to long unless necessary. +Also set OPTERR=0 to avoid printing errors and do it yourself for UX +consistency. + +```sh +OPTERR=0 +while getopts "v" arg; do + case $arg in + v) + verbose=1 + ;; + esac +done +``` + +Naming +------ + +Use `UPPERCASE` variables for global variables and `lowercase` for temporary or +local variables. + +Markdown +======== + +Headers +------- + +For 1st and 2nd level headers, use `===` and `---` delimiters and underline the +whole title. Otherwise use `###`. + +```markdown +Top level title +=============== + +Sub title +--------- + +### Header 3 + +#### Header 4 + +##### Header 5 + +###### Header 6 +``` + +Lists +----- + +Use hyphens for unordered lists for consistency, do not indent top level lists, +then indent by two spaces each level + +```markdown +- unordered list 1 +- unordered list 2 + - sub unordered item + +1. unordered list 1 +2. unordered list 2 + 2.1. sub unordered item +``` + +Code blocks +----------- + +You can use three backticks and the language specifier or just indent a block by +for leading spaces if you don't need syntax. + + ```cpp + std::cout << "hello world" << std::endl; + ``` + +And without syntax: + +```markdown + This is simple code block. +``` + +Tables +------ + +Tables are supported and formatted as following: + +```markdown +| header 1 | header 2 | +|----------|----------| +| item 1 | item 2 | +``` + +Alerts +------ + +It's possible to prefix a paragraph by one of the following topic, it renders a +different block depending on the output format: + +- Note: +- Warning: +- Danger: + +Then, if the paragraph is too long, indent the text correctly. + +```markdown +Note: this is an information block that is too long to fit between the limits so + it is split and indented. +```