1# curl C code style
2
3Source code that has a common style is easier to read than code that uses
4different styles in different places. It helps making the code feel like one
5single code base. Easy-to-read is a very important property of code and helps
6making it easier to review when new things are added and it helps debugging
7code when developers are trying to figure out why things go wrong. A unified
8style is more important than individual contributors having their own personal
9tastes satisfied.
10
11Our 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
13the build system when built after `./configure --enable-debug` has been used.
14
15It is normally not a problem for anyone to follow the guidelines, as you just
16need to copy the style already used in the source code and there are no
17particularly unusual rules in our set of rules.
18
19We also work hard on writing code that are warning-free on all the major
20platforms and in general on as many platforms as possible. Code that obviously
21will cause warnings will not be accepted as-is.
22
23## Naming
24
25Try using a non-confusing naming scheme for your new functions and variable
26names. It doesn't necessarily have to mean that you should use the same as in
27other places of the code, just that the names should be logical,
28understandable and be named according to what they're used for. File-local
29functions should be made static. We like lower case names.
30
31See the [INTERNALS](INTERNALS.md) document on how we name non-exported
32library-global symbols.
33
34## Indenting
35
36We use only spaces for indentation, never TABs. We use two spaces for each new
37open brace.
38
39    if(something_is_true) {
40      while(second_statement == fine) {
41        moo();
42      }
43    }
44
45## Comments
46
47Since we write C89 code, `//` comments are not allowed. They weren't
48introduced in the C standard until C99. We use only `/*` and `*/` comments:
49
50    /* this is a comment */
51
52## Long lines
53
54Source code in curl may never be wider than 79 columns and there are two
55reasons for maintaining this even in the modern era of very large and high
56resolution screens:
57
581. Narrower columns are easier to read than very wide ones. There's a reason
59   newspapers have used columns for decades or centuries.
60
612. 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
68In if/while/do/for expressions, we write the open brace on the same line as
69the keyword and we then set the closing brace on the same indentation level as
70the initial keyword. Like this:
71
72    if(age < 40) {
73      /* clearly a youngster */
74    }
75
76You may omit the braces if they would contain only a one-line statement:
77
78    if(!x)
79      continue;
80
81For 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
90When adding an `else` clause to a conditional expression using braces, we add
91it 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
102When writing expressions using if/while/do/for, there shall be no space
103between the keyword and the open parenthesis. Like this:
104
105    while(1) {
106      /* loop forever */
107    }
108
109## Use boolean conditions
110
111Rather than test a conditional value such as a bool against TRUE or FALSE, a
112pointer against NULL or != NULL and an int against zero or not zero in
113if/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
123To increase readability and reduce complexity of conditionals, we avoid
124assigning variables within if/while conditions. We frown upon this style:
125
126    if((ptr = malloc(100)) == NULL)
127      return NULL;
128
129and 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
137We never write multiple statements on the same source line, even for very
138short if() conditions.
139
140    if(a)
141      return TRUE;
142    else if(b)
143      return FALSE;
144
145and NEVER:
146
147    if(a) return TRUE;
148    else if(b) return FALSE;
149
150## Space around operators
151
152Please use spaces on both sides of operators in C expressions.  Postfix `(),
153[], ->, ., ++, --` and Unary `+, - !, ~, &` operators excluded they should
154have no space.
155
156Examples:
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## Column alignment
171
172Some statements cannot be completed on a single line because the line would
173be too long, the statement too hard to read, or due to other style guidelines
174above. In such a case the statement will span multiple lines.
175
176If a continuation line is part of an expression or sub-expression then you
177should align on the appropriate column so that it's easy to tell what part of
178the statement it is. Operators should not start continuation lines. In other
179cases follow the 2-space indent guideline. Here are some examples from libcurl:
180
181~~~c
182    if(Curl_pipeline_wanted(handle->multi, CURLPIPE_HTTP1) &&
183       (handle->set.httpversion != CURL_HTTP_VERSION_1_0) &&
184       (handle->set.httpreq == HTTPREQ_GET ||
185        handle->set.httpreq == HTTPREQ_HEAD))
186      /* didn't ask for HTTP/1.0 and a GET or HEAD */
187      return TRUE;
188~~~
189
190~~~c
191  case CURLOPT_KEEP_SENDING_ON_ERROR:
192    data->set.http_keep_sending_on_error = (0 != va_arg(param, long)) ?
193                                           TRUE : FALSE;
194    break;
195~~~
196
197~~~c
198    data->set.http_disable_hostname_check_before_authentication =
199      (0 != va_arg(param, long)) ? TRUE : FALSE;
200~~~
201
202~~~c
203  if(option) {
204    result = parse_login_details(option, strlen(option),
205                                 (userp ? &user : NULL),
206                                 (passwdp ? &passwd : NULL),
207                                 NULL);
208  }
209~~~
210
211~~~c
212        DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing "
213                     "server response left\n",
214                     (int)clipamount));
215~~~
216
217## Platform dependent code
218
219Use `#ifdef HAVE_FEATURE` to do conditional code. We avoid checking for
220particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE
221shall be generated by the configure script for unix-like systems and they are
222hard-coded in the config-[system].h files for the others.
223
224We also encourage use of macros/functions that possibly are empty or defined
225to constants when libcurl is built without that feature, to make the code
226seamless. Like this style where the `magic()` function works differently
227depending on a build-time conditional:
228
229    #ifdef HAVE_MAGIC
230    void magic(int a)
231    {
232      return a + 2;
233    }
234    #else
235    #define magic(x) 1
236    #endif
237
238    int content = magic(3);
239