Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/CODE_STYLE.md @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 # curl C code style
2
3 Source code that has a common style is easier to read than code that uses
4 different styles in different places. It helps making the code feel like one
5 single code base. Easy-to-read is a very important property of code and helps
6 making it easier to review when new things are added and it helps debugging
7 code when developers are trying to figure out why things go wrong. A unified
8 style is more important than individual contributors having their own personal
9 tastes satisfied.
10
11 Our C code has a few style rules. Most of them are verified and upheld by the
12 `lib/checksrc.pl` script. Invoked with `make checksrc` or even by default by
13 the build system when built after `./configure --enable-debug` has been used.
14
15 It is normally not a problem for anyone to follow the guidelines, as you just
16 need to copy the style already used in the source code and there are no
17 particularly unusual rules in our set of rules.
18
19 We also work hard on writing code that are warning-free on all the major
20 platforms and in general on as many platforms as possible. Code that obviously
21 will cause warnings will not be accepted as-is.
22
23 ## Naming
24
25 Try using a non-confusing naming scheme for your new functions and variable
26 names. It doesn't necessarily have to mean that you should use the same as in
27 other places of the code, just that the names should be logical,
28 understandable and be named according to what they're used for. File-local
29 functions should be made static. We like lower case names.
30
31 See the [INTERNALS](INTERNALS.md) document on how we name non-exported
32 library-global symbols.
33
34 ## Indenting
35
36 We use only spaces for indentation, never TABs. We use two spaces for each new
37 open brace.
38
39 if(something_is_true) {
40 while(second_statement == fine) {
41 moo();
42 }
43 }
44
45 ## Comments
46
47 Since we write C89 code, **//** comments are not allowed. They weren't
48 introduced in the C standard until C99. We use only **/* comments */**.
49
50 /* this is a comment */
51
52 ## Long lines
53
54 Source code in curl may never be wider than 79 columns and there are two
55 reasons for maintaining this even in the modern era of very large and high
56 resolution screens:
57
58 1. Narrower columns are easier to read than very wide ones. There's a reason
59 newspapers have used columns for decades or centuries.
60
61 2. Narrower columns allow developers to easier show multiple pieces of code
62 next to each other in different windows. I often have two or three source
63 code windows next to each other on the same screen - as well as multiple
64 terminal and debugging windows.
65
66 ## Braces
67
68 In if/while/do/for expressions, we write the open brace on the same line as
69 the keyword and we then set the closing brace on the same indentation level as
70 the initial keyword. Like this:
71
72 if(age < 40) {
73 /* clearly a youngster */
74 }
75
76 You may omit the braces if they would contain only a one-line statement:
77
78 if(!x)
79 continue;
80
81 For functions the opening brace should be on a separate line:
82
83 int main(int argc, char **argv)
84 {
85 return 1;
86 }
87
88 ## 'else' on the following line
89
90 When adding an **else** clause to a conditional expression using braces, we
91 add it on a new line after the closing brace. Like this:
92
93 if(age < 40) {
94 /* clearly a youngster */
95 }
96 else {
97 /* probably grumpy */
98 }
99
100 ## No space before parentheses
101
102 When writing expressions using if/while/do/for, there shall be no space
103 between the keyword and the open parenthesis. Like this:
104
105 while(1) {
106 /* loop forever */
107 }
108
109 ## Use boolean conditions
110
111 Rather than test a conditional value such as a bool against TRUE or FALSE, a
112 pointer against NULL or != NULL and an int against zero or not zero in
113 if/while conditions we prefer:
114
115 result = do_something();
116 if(!result) {
117 /* something went wrong */
118 return result;
119 }
120
121 ## No assignments in conditions
122
123 To increase readability and reduce complexity of conditionals, we avoid
124 assigning variables within if/while conditions. We frown upon this style:
125
126 if((ptr = malloc(100)) == NULL)
127 return NULL;
128
129 and instead we encourage the above version to be spelled out more clearly:
130
131 ptr = malloc(100);
132 if(!ptr)
133 return NULL;
134
135 ## New block on a new line
136
137 We never write multiple statements on the same source line, even for very
138 short if() conditions.
139
140 if(a)
141 return TRUE;
142 else if(b)
143 return FALSE;
144
145 and NEVER:
146
147 if(a) return TRUE;
148 else if(b) return FALSE;
149
150 ## Space around operators
151
152 Please use spaces on both sides of operators in C expressions. Postfix **(),
153 [], ->, ., ++, --** and Unary **+, - !, ~, &** operators excluded they should
154 have no space.
155
156 Examples:
157
158 bla = func();
159 who = name[0];
160 age += 1;
161 true = !false;
162 size += -2 + 3 * (a + b);
163 ptr->member = a++;
164 struct.field = b--;
165 ptr = &address;
166 contents = *pointer;
167 complement = ~bits;
168 empty = (!*string) ? TRUE : FALSE;
169
170 ## No parentheses for return values
171
172 We use the 'return' statement without extra parentheses around the value:
173
174 int works(void)
175 {
176 return TRUE;
177 }
178
179 ## Parentheses for sizeof arguments
180
181 When using the sizeof operator in code, we prefer it to be written with
182 parentheses around its argument:
183
184 int size = sizeof(int);
185
186 ## Column alignment
187
188 Some statements cannot be completed on a single line because the line would be
189 too long, the statement too hard to read, or due to other style guidelines
190 above. In such a case the statement will span multiple lines.
191
192 If a continuation line is part of an expression or sub-expression then you
193 should align on the appropriate column so that it's easy to tell what part of
194 the statement it is. Operators should not start continuation lines. In other
195 cases follow the 2-space indent guideline. Here are some examples from
196 libcurl:
197
198 if(Curl_pipeline_wanted(handle->multi, CURLPIPE_HTTP1) &&
199 (handle->set.httpversion != CURL_HTTP_VERSION_1_0) &&
200 (handle->set.httpreq == HTTPREQ_GET ||
201 handle->set.httpreq == HTTPREQ_HEAD))
202 /* didn't ask for HTTP/1.0 and a GET or HEAD */
203 return TRUE;
204
205 If no parenthesis, use the default indent:
206
207 data->set.http_disable_hostname_check_before_authentication =
208 (0 != va_arg(param, long)) ? TRUE : FALSE;
209
210 Function invoke with an open parenthesis:
211
212 if(option) {
213 result = parse_login_details(option, strlen(option),
214 (userp ? &user : NULL),
215 (passwdp ? &passwd : NULL),
216 NULL);
217 }
218
219 Align with the "current open" parenthesis:
220
221 DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing "
222 "server response left\n",
223 (int)clipamount));
224
225 ## Platform dependent code
226
227 Use **#ifdef HAVE_FEATURE** to do conditional code. We avoid checking for
228 particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE
229 shall be generated by the configure script for unix-like systems and they are
230 hard-coded in the `config-[system].h` files for the others.
231
232 We also encourage use of macros/functions that possibly are empty or defined
233 to constants when libcurl is built without that feature, to make the code
234 seamless. Like this example where the **magic()** function works differently
235 depending on a build-time conditional:
236
237 #ifdef HAVE_MAGIC
238 void magic(int a)
239 {
240 return a + 2;
241 }
242 #else
243 #define magic(x) 1
244 #endif
245
246 int content = magic(3);