Mercurial > vanilla

annotate STYLE.md @ 1330:8996e7c01cf2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
graphics/libjpeg-turbo: upgrade to 2.1.2
author David Demelier <markand@malikania.fr>
date Sun, 21 Nov 2021 15:26:06 +0100
parents a133976e0783
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
902
a133976e0783 vanilla: remove all origins, closes #2203
David Demelier <markand@malikania.fr>
parents: 594
diff changeset
26 Some extensions that are widely supported are allowed, all scripts must run with
a133976e0783 vanilla: remove all origins, closes #2203
David Demelier <markand@malikania.fr>
parents: 594
diff changeset
27 `busybox sh` and `dash`, also make sure that they do work with more popular
a133976e0783 vanilla: remove all origins, closes #2203
David Demelier <markand@malikania.fr>
parents: 594
diff changeset
28 shells like `bash` and `zsh`.
a133976e0783 vanilla: remove all origins, closes #2203
David Demelier <markand@malikania.fr>
parents: 594
diff changeset
29
31
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 Style
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 -----
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 - Try to keep lines shorter than 80 columns
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
34
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 Functions
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 ---------
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
37
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 Don't use `function` keyword, just keep the function name.
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 ```sh
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 usage()
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 {
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 }
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 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
47 avoid collisions with global commands.
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 ```sh
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 foo_clean()
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 foo_process()
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 {
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 Options
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 -------
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 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
63 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
64 consistency.
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
65
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 ```sh
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 OPTERR=0
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 while getopts "v" arg; do
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 case $arg in
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 v)
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 verbose=1
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 esac
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 done
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 Naming
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 Use `UPPERCASE` variables for global variables and `lowercase` for temporary or
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 local variables.
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
82
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 Markdown
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 Headers
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
89 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
90 whole title. Otherwise use `###`.
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 ```markdown
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
93 Top level title
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 Sub title
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 ---------
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 3
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 4
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 ##### Header 5
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
104
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 ###### Header 6
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 Lists
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 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
112 then indent by two spaces each level
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
113
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 ```markdown
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 - unordered list 1
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 - unordered list 2
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 - 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 1. unordered list 1
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 2. unordered list 2
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 2.1. sub unordered item
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 Code blocks
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 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
128 for leading spaces if you don't need syntax.
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 ```cpp
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 std::cout << "hello world" << std::endl;
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 ```
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
133
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
134 And without syntax:
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 ```markdown
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
137 This is simple code block.
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
140 Tables
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 ------
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
142
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
143 Tables are supported and formatted as following:
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
144
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
145 ```markdown
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
146 | header 1 | header 2 |
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
147 |----------|----------|
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
148 | item 1 | item 2 |
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
151 Alerts
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
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
154 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
155 different block depending on the output format:
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 - Note:
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
158 - Warning:
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
159 - Danger:
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
160
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
161 Then, if the paragraph is too long, indent the text correctly.
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
162
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 ```markdown
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
164 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
165 it is split and indented.
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
166 ```