Mercurial > vanilla
comparison 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 |
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 ``` |