STYLE.md

Fri, 15 Nov 2019 20:11:00 +0100

author
David Demelier <markand@malikania.fr>
date
Fri, 15 Nov 2019 20:11:00 +0100
changeset 1210
422313c3fcbd
parent 902
a133976e0783
permissions
-rw-r--r--

text/rarian: initial import, closes #2311

Vanilla Linux 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.

Some extensions that are widely supported are allowed, all scripts must run with
`busybox sh` and `dash`, also make sure that they do work with more popular
shells like `bash` and `zsh`.

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.

mercurial