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
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 the
13 build system when built after `./configure --enable-debug` has been used.
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.
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.
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.
31 See the INTERNALS document on how we name non-exported library-global symbols.
35 We use only spaces for indentation, never TABs. We use two spaces for each new
38 if(something_is_true) {
39 while(second_statement == fine) {
46 Since we write C89 code, `//` comments are not allowed. They weren't
47 introduced in the C standard until C99. We use only `/*` and `*/` comments:
49 /* this is a comment */
53 Source code in curl may never be wider than 80 columns and there are two
54 reasons for maintaining this even in the modern era of very large and high
57 1. Narrower columns are easier to read than very wide ones. There's a reason
58 newspapers have used columns for decades or centuries.
60 2. Narrower columns allow developers to easier show multiple pieces of code
61 next to each other in different windows. I often have two or three source
62 code windows next to each other on the same screen - as well as multiple
63 terminal and debugging windows.
67 In if/while/do/for expressions, we write the open brace on the same line as
68 the keyword and we then set the closing brace on the same indentation level as
69 the initial keyword. Like this:
72 /* clearly a youngster */
75 When we write functions however, the opening brace should be in the first
76 column of the first line:
78 int main(int argc, char **argv)
83 ## 'else' on the following line
85 When adding an `else` clause to a conditional expression using braces, we add
86 it on a new line after the closing brace. Like this:
89 /* clearly a youngster */
95 ## No space before parentheses
97 When writing expressions using if/while/do/for, there shall be no space
98 between the keyword and the open parenthesis. Like this:
104 ## Use boolean conditions
106 Rather than test a conditional value such as a bool against TRUE or FALSE, a
107 pointer against NULL or != NULL and an int against zero or not zero in
108 if/while conditions we prefer:
110 result = do_something();
112 /* something went wrong */
116 ## No assignments in conditions
118 To increase readability and reduce complexity of conditionals, we avoid
119 assigning variables within if/while conditions. We frown upon this style:
121 if((ptr = malloc(100)) == NULL)
124 and instead we encourage the above version to be spelled out more clearly:
130 ## New block on a new line
132 We never write multiple statements on the same source line, even for very
133 short if() conditions.
143 else if(b) return FALSE;
145 ## Space around operators
147 Please use spaces on both sides of operators in C expressions. Postfix `(),
148 [], ->, ., ++, --` and Unary `+, - !, ~, &` operators excluded they should
157 size += -2 + 3 * (a + b);
163 empty = (!*string) ? TRUE : FALSE;
165 ## Platform dependent code
167 Use `#ifdef HAVE_FEATURE` to do conditional code. We avoid checking for
168 particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE
169 shall be generated by the configure script for unix-like systems and they are
170 hard-coded in the config-[system].h files for the others.
172 We also encourage use of macros/functions that possibly are empty or defined
173 to constants when libcurl is built without that feature, to make the code
174 seamless. Like this style where the `magic()` function works differently
175 depending on a build-time conditional:
186 int content = magic(3);