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