Mercurial > vanilla

comparison STYLE.md @ 31:afb6f8eb89da

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
vanilla: add more documentation
author David Demelier <markand@malikania.fr>
date Tue, 26 Feb 2019 09:16:42 +0100
parents
children 3cffdd760a86
comparison
equal deleted inserted replaced
30:345ba1fec137 31:afb6f8eb89da
1 vanilla CODING STYLE
2 ====================
3
4 File content
5 ============
6
7 - Use UTF-8 charset,
8 - Use Unix line endings,
9 - Never write two blank consecutives blank lines.
10
11 Indent
12 ======
13
14 Use tabs to indent and spaces for alignment. Tabs are meant and designed for
15 indenting code and have the advantage of being configurable. On the other hand
16 to keep code clean, you must align content with spaces only *within* a line.
17
18 Note: we recommend 8 columns to avoid high number of indentations.
19
20 Shell
21 =====
22
23 In shell programming try to stick with POSIX shell whenever possible. Otherwise,
24 set the shebang to a different shell.
25
26 Style
27 -----
28
29 - Try to keep lines shorter than 80 columns
30
31 Functions
32 ---------
33
34 Don't use `function` keyword, just keep the function name.
35
36 ```sh
37 usage()
38 {
39 }
40 ```
41
42 It's usually recommended to prefix functions names with the program name to
43 avoid collisions with global commands.
44
45 ```sh
46 foo_clean()
47 {
48 }
49
50 foo_process()
51 {
52 }
53 ```
54
55 Options
56 -------
57
58 For options, use `getopts` and prefer short options to long unless necessary.
59 Also set OPTERR=0 to avoid printing errors and do it yourself for UX
60 consistency.
61
62 ```sh
63 OPTERR=0
64 while getopts "v" arg; do
65 case $arg in
66 v)
67 verbose=1
68 ;;
69 esac
70 done
71 ```
72
73 Naming
74 ------
75
76 Use `UPPERCASE` variables for global variables and `lowercase` for temporary or
77 local variables.
78
79 Markdown
80 ========
81
82 Headers
83 -------
84
85 For 1st and 2nd level headers, use `===` and `---` delimiters and underline the
86 whole title. Otherwise use `###`.
87
88 ```markdown
89 Top level title
90 ===============
91
92 Sub title
93 ---------
94
95 ### Header 3
96
97 #### Header 4
98
99 ##### Header 5
100
101 ###### Header 6
102 ```
103
104 Lists
105 -----
106
107 Use hyphens for unordered lists for consistency, do not indent top level lists,
108 then indent by two spaces each level
109
110 ```markdown
111 - unordered list 1
112 - unordered list 2
113 - sub unordered item
114
115 1. unordered list 1
116 2. unordered list 2
117 2.1. sub unordered item
118 ```
119
120 Code blocks
121 -----------
122
123 You can use three backticks and the language specifier or just indent a block by
124 for leading spaces if you don't need syntax.
125
126 ```cpp
127 std::cout << "hello world" << std::endl;
128 ```
129
130 And without syntax:
131
132 ```markdown
133 This is simple code block.
134 ```
135
136 Tables
137 ------
138
139 Tables are supported and formatted as following:
140
141 ```markdown
142 | header 1 | header 2 |
143 |----------|----------|
144 | item 1 | item 2 |
145 ```
146
147 Alerts
148 ------
149
150 It's possible to prefix a paragraph by one of the following topic, it renders a
151 different block depending on the output format:
152
153 - Note:
154 - Warning:
155 - Danger:
156
157 Then, if the paragraph is too long, indent the text correctly.
158
159 ```markdown
160 Note: this is an information block that is too long to fit between the limits so
161 it is split and indented.
162 ```