Mercurial > vanilla

annotate STYLE.md @ 187:65736f6be915

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
core/ca-certificates: initial import, closes #1389
author David Demelier <markand@malikania.fr>
date Sun, 17 Mar 2019 18:02:58 +0100
parents afb6f8eb89da
children 3cffdd760a86
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
31
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 vanilla CODING STYLE
afb6f8eb89da vanilla: add more documentation
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 ====================
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 ```