CINXE.COM

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>Code style</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"> <link rel="stylesheet" type="text/css" href="/curl.css"> <link rel="shortcut icon" href="/favicon.ico"> <link rel="icon" href="/logo/curl-symbol.svg" type="image/svg+xml"> <link rel="alternate" type="application/rss+xml" title="cURL Releases" href="https://github.com/curl/curl/releases.atom"> <style type="text/css"> div.sourceCode { background-color: #f0f0f0; padding: 4px 8px 4px 4px; } </style> </head> <body> <div class="main"> <div class="menu"> <div class="dropdown"> <a class="dropbtn" href="/dev/">Dev-related docs</a> <div class="dropdown-content"> <a href="/dev/code-review.html">Code Review</a> <a href="/dev/code-style.html">Code Style</a> <a href="/dev/contribute.html">Contribute</a> <a href="/dev/deprecate.html">Deprecate</a> <a href="/dev/internals.html">Internals</a> <a href="/dev/new-protocol.html">New protocol</a> <a href="/dev/release-procedure.html">Release procedure</a> <a href="/dev/roadmap.html">Roadmap</a> <a href="/dev/runtests.html">Run tests</a> <a href="/dev/source.html">Source code</a> <a href="/rfc/">Specifications</a> <a href="https://testclutch.curl.se/">Test Clutch</a> <a href="/dev/testcurl.html">Test curl</a> <a href="/dev/test-fileformat.html">Test case file format</a> <a href="/dev/tests-overview.html">Tests Overview</a> <a href="/dev/vuln-disclosure.html">Vulnerability Disclosure Policy</a> </div> </div> <div class="dropdown"> <a class="dropbtn" href="/dev/./">Current status</a> <div class="dropdown-content"> <a href="/dev/builds.html">Autobuilds</a> <a href="/snapshots/">Daily snapshots</a> <a href="/dashboard.html">Dashboard</a> <a href="/dev/feature-window.html">Feature window</a> <a href="/gitstats/">git stats</a> <a href="https://github.com/curl/curl/issues" target="_blank">Issues (github)</a> <a href="https://github.com/curl/curl/pulls" target="_blank">Pull requests (github)</a> <a href="/dev/release-notes.html">Release Notes</a> </div> </div> </div> <div class="contents"> <div class="where"><a href="/">curl</a> / <a href="/dev/">Development</a> / code style</div> <div class="relatedbox"> Related: <a href="code-review.html">Code review</a> <a href="contribute.html">Contribute</a> <a href="/mail/">Mailing Lists</a> <a href="internals.html">Internals</a> </div>  <h1 id="curl-c-code-style">curl C code style</h1> Source code that has a common style is easier to read than code that uses different styles in different places. It helps making the code feel like one single code base. Easy-to-read is an important property of code and helps making it easier to review when new things are added and it helps debugging code when developers are trying to figure out why things go wrong. A unified style is more important than individual contributors having their own personal tastes satisfied. Our C code has a few style rules. Most of them are verified and upheld by the <code>scripts/checksrc.pl</code> script. Invoked with <code>make checksrc</code> or even by default by the build system when built after <code>./configure --enable-debug</code> has been used. It is normally not a problem for anyone to follow the guidelines, as you just need to copy the style already used in the source code and there are no particularly unusual rules in our set of rules. We also work hard on writing code that are warning-free on all the major platforms and in general on as many platforms as possible. Code that obviously causes warnings is not accepted as-is. <h2 id="naming">Naming</h2> Try using a non-confusing naming scheme for your new functions and variable names. It does not necessarily have to mean that you should use the same as in other places of the code, just that the names should be logical, understandable and be named according to what they are used for. File-local functions should be made static. We like lower case names. See the <a href="https://curl.se/dev/internals.html#symbols">INTERNALS</a> document on how we name non-exported library-global symbols. <h2 id="indenting">Indenting</h2> We use only spaces for indentation, never TABs. We use two spaces for each new open brace. <div class="sourceCode" id="cb1"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a>if(something_is_true) { <a href="#cb1-2" aria-hidden="true" tabindex="-1"></a> while(second_statement == fine) { <a href="#cb1-3" aria-hidden="true" tabindex="-1"></a> moo(); <a href="#cb1-4" aria-hidden="true" tabindex="-1"></a> } <a href="#cb1-5" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> <h2 id="comments">Comments</h2> Since we write C89 code, // comments are not allowed. They were not introduced in the C standard until C99. We use only /* comments */. <div class="sourceCode" id="cb2"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>/* this is a comment */</code></pre></div> <h2 id="long-lines">Long lines</h2> Source code in curl may never be wider than 79 columns and there are two reasons for maintaining this even in the modern era of large and high resolution screens: <ol type="1"> <li>Narrower columns are easier to read than wide ones. There is a reason newspapers have used columns for decades or centuries.</li> <li>Narrower columns allow developers to easier show multiple pieces of code next to each other in different windows. It allows two or three source code windows next to each other on the same screen - as well as multiple terminal and debugging windows.</li> </ol> <h2 id="braces">Braces</h2> In if/while/do/for expressions, we write the open brace on the same line as the keyword and we then set the closing brace on the same indentation level as the initial keyword. Like this: <div class="sourceCode" id="cb3"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a>if(age < 40) { <a href="#cb3-2" aria-hidden="true" tabindex="-1"></a> /* clearly a youngster */ <a href="#cb3-3" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> You may omit the braces if they would contain only a one-line statement: <div class="sourceCode" id="cb4"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a>if(!x) <a href="#cb4-2" aria-hidden="true" tabindex="-1"></a> continue;</code></pre></div> For functions the opening brace should be on a separate line: <div class="sourceCode" id="cb5"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a>int main(int argc, char **argv) <a href="#cb5-2" aria-hidden="true" tabindex="-1"></a>{ <a href="#cb5-3" aria-hidden="true" tabindex="-1"></a> return 1; <a href="#cb5-4" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> <h2 id="else-on-the-following-line">'else' on the following line</h2> When adding an else clause to a conditional expression using braces, we add it on a new line after the closing brace. Like this: <div class="sourceCode" id="cb6"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a>if(age < 40) { <a href="#cb6-2" aria-hidden="true" tabindex="-1"></a> /* clearly a youngster */ <a href="#cb6-3" aria-hidden="true" tabindex="-1"></a>} <a href="#cb6-4" aria-hidden="true" tabindex="-1"></a>else { <a href="#cb6-5" aria-hidden="true" tabindex="-1"></a> /* probably grumpy */ <a href="#cb6-6" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> <h2 id="no-space-before-parentheses">No space before parentheses</h2> When writing expressions using if/while/do/for, there shall be no space between the keyword and the open parenthesis. Like this: <div class="sourceCode" id="cb7"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a>while(1) { <a href="#cb7-2" aria-hidden="true" tabindex="-1"></a> /* loop forever */ <a href="#cb7-3" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> <h2 id="use-boolean-conditions">Use boolean conditions</h2> Rather than test a conditional value such as a bool against TRUE or FALSE, a pointer against NULL or != NULL and an int against zero or not zero in if/while conditions we prefer: <div class="sourceCode" id="cb8"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb8-1" aria-hidden="true" tabindex="-1"></a>result = do_something(); <a href="#cb8-2" aria-hidden="true" tabindex="-1"></a>if(!result) { <a href="#cb8-3" aria-hidden="true" tabindex="-1"></a> /* something went wrong */ <a href="#cb8-4" aria-hidden="true" tabindex="-1"></a> return result; <a href="#cb8-5" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> <h2 id="no-assignments-in-conditions">No assignments in conditions</h2> To increase readability and reduce complexity of conditionals, we avoid assigning variables within if/while conditions. We frown upon this style: <div class="sourceCode" id="cb9"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a>if((ptr = malloc(100)) == NULL) <a href="#cb9-2" aria-hidden="true" tabindex="-1"></a> return NULL;</code></pre></div> and instead we encourage the above version to be spelled out more clearly: <div class="sourceCode" id="cb10"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a>ptr = malloc(100); <a href="#cb10-2" aria-hidden="true" tabindex="-1"></a>if(!ptr) <a href="#cb10-3" aria-hidden="true" tabindex="-1"></a> return NULL;</code></pre></div> <h2 id="new-block-on-a-new-line">New block on a new line</h2> We never write multiple statements on the same source line, even for short if() conditions. <div class="sourceCode" id="cb11"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a>if(a) <a href="#cb11-2" aria-hidden="true" tabindex="-1"></a> return TRUE; <a href="#cb11-3" aria-hidden="true" tabindex="-1"></a>else if(b) <a href="#cb11-4" aria-hidden="true" tabindex="-1"></a> return FALSE;</code></pre></div> and NEVER: <div class="sourceCode" id="cb12"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb12-1" aria-hidden="true" tabindex="-1"></a>if(a) return TRUE; <a href="#cb12-2" aria-hidden="true" tabindex="-1"></a>else if(b) return FALSE;</code></pre></div> <h2 id="space-around-operators">Space around operators</h2> Please use spaces on both sides of operators in C expressions. Postfix (), [], ->, ., ++, -- and Unary +, -, !, ~, & operators excluded they should have no space. Examples: <div class="sourceCode" id="cb13"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb13-1" aria-hidden="true" tabindex="-1"></a>bla = func(); <a href="#cb13-2" aria-hidden="true" tabindex="-1"></a>who = name[0]; <a href="#cb13-3" aria-hidden="true" tabindex="-1"></a>age += 1; <a href="#cb13-4" aria-hidden="true" tabindex="-1"></a>true = !false; <a href="#cb13-5" aria-hidden="true" tabindex="-1"></a>size += -2 + 3 * (a + b); <a href="#cb13-6" aria-hidden="true" tabindex="-1"></a>ptr->member = a++; <a href="#cb13-7" aria-hidden="true" tabindex="-1"></a>struct.field = b--; <a href="#cb13-8" aria-hidden="true" tabindex="-1"></a>ptr = &address; <a href="#cb13-9" aria-hidden="true" tabindex="-1"></a>contents = *pointer; <a href="#cb13-10" aria-hidden="true" tabindex="-1"></a>complement = ~bits; <a href="#cb13-11" aria-hidden="true" tabindex="-1"></a>empty = (!*string) ? TRUE : FALSE;</code></pre></div> <h2 id="no-parentheses-for-return-values">No parentheses for return values</h2> We use the 'return' statement without extra parentheses around the value: <div class="sourceCode" id="cb14"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb14-1" aria-hidden="true" tabindex="-1"></a>int works(void) <a href="#cb14-2" aria-hidden="true" tabindex="-1"></a>{ <a href="#cb14-3" aria-hidden="true" tabindex="-1"></a> return TRUE; <a href="#cb14-4" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> <h2 id="parentheses-for-sizeof-arguments">Parentheses for sizeof arguments</h2> When using the sizeof operator in code, we prefer it to be written with parentheses around its argument: <div class="sourceCode" id="cb15"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb15-1" aria-hidden="true" tabindex="-1"></a>int size = sizeof(int);</code></pre></div> <h2 id="column-alignment">Column alignment</h2> Some statements cannot be completed on a single line because the line would be too long, the statement too hard to read, or due to other style guidelines above. In such a case the statement spans multiple lines. If a continuation line is part of an expression or sub-expression then you should align on the appropriate column so that it is easy to tell what part of the statement it is. Operators should not start continuation lines. In other cases follow the 2-space indent guideline. Here are some examples from libcurl: <div class="sourceCode" id="cb16"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb16-1" aria-hidden="true" tabindex="-1"></a>if(Curl_pipeline_wanted(handle->multi, CURLPIPE_HTTP1) && <a href="#cb16-2" aria-hidden="true" tabindex="-1"></a> (handle->set.httpversion != CURL_HTTP_VERSION_1_0) && <a href="#cb16-3" aria-hidden="true" tabindex="-1"></a> (handle->set.httpreq == HTTPREQ_GET || <a href="#cb16-4" aria-hidden="true" tabindex="-1"></a> handle->set.httpreq == HTTPREQ_HEAD)) <a href="#cb16-5" aria-hidden="true" tabindex="-1"></a> /* did not ask for HTTP/1.0 and a GET or HEAD */ <a href="#cb16-6" aria-hidden="true" tabindex="-1"></a> return TRUE;</code></pre></div> If no parenthesis, use the default indent: <div class="sourceCode" id="cb17"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb17-1" aria-hidden="true" tabindex="-1"></a>data->set.http_disable_hostname_check_before_authentication = <a href="#cb17-2" aria-hidden="true" tabindex="-1"></a> (0 != va_arg(param, long)) ? TRUE : FALSE;</code></pre></div> Function invoke with an open parenthesis: <div class="sourceCode" id="cb18"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb18-1" aria-hidden="true" tabindex="-1"></a>if(option) { <a href="#cb18-2" aria-hidden="true" tabindex="-1"></a> result = parse_login_details(option, strlen(option), <a href="#cb18-3" aria-hidden="true" tabindex="-1"></a> (userp ? &user : NULL), <a href="#cb18-4" aria-hidden="true" tabindex="-1"></a> (passwdp ? &passwd : NULL), <a href="#cb18-5" aria-hidden="true" tabindex="-1"></a> NULL); <a href="#cb18-6" aria-hidden="true" tabindex="-1"></a>}</code></pre></div> Align with the "current open" parenthesis: <div class="sourceCode" id="cb19"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb19-1" aria-hidden="true" tabindex="-1"></a>DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing " <a href="#cb19-2" aria-hidden="true" tabindex="-1"></a> "server response left\n", <a href="#cb19-3" aria-hidden="true" tabindex="-1"></a> (int)clipamount));</code></pre></div> <h2 id="platform-dependent-code">Platform dependent code</h2> Use #ifdef HAVE_FEATURE to do conditional code. We avoid checking for particular operating systems or hardware in the #ifdef lines. The HAVE_FEATURE shall be generated by the configure script for Unix-like systems and they are hard-coded in the <code>config-[system].h</code> files for the others. We also encourage use of macros/functions that possibly are empty or defined to constants when libcurl is built without that feature, to make the code seamless. Like this example where the magic() function works differently depending on a build-time conditional: <div class="sourceCode" id="cb20"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb20-1" aria-hidden="true" tabindex="-1"></a>#ifdef HAVE_MAGIC <a href="#cb20-2" aria-hidden="true" tabindex="-1"></a>void magic(int a) <a href="#cb20-3" aria-hidden="true" tabindex="-1"></a>{ <a href="#cb20-4" aria-hidden="true" tabindex="-1"></a> return a + 2; <a href="#cb20-5" aria-hidden="true" tabindex="-1"></a>} <a href="#cb20-6" aria-hidden="true" tabindex="-1"></a>#else <a href="#cb20-7" aria-hidden="true" tabindex="-1"></a>#define magic(x) 1 <a href="#cb20-8" aria-hidden="true" tabindex="-1"></a>#endif <a href="#cb20-9" aria-hidden="true" tabindex="-1"></a> <a href="#cb20-10" aria-hidden="true" tabindex="-1"></a>int content = magic(3);</code></pre></div> <h2 id="no-typedefed-structs">No typedefed structs</h2> Use structs by all means, but do not typedef them. Use the <code>struct name</code> way of identifying them: <div class="sourceCode" id="cb21"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb21-1" aria-hidden="true" tabindex="-1"></a>struct something { <a href="#cb21-2" aria-hidden="true" tabindex="-1"></a> void *valid; <a href="#cb21-3" aria-hidden="true" tabindex="-1"></a> size_t way_to_write; <a href="#cb21-4" aria-hidden="true" tabindex="-1"></a>}; <a href="#cb21-5" aria-hidden="true" tabindex="-1"></a>struct something instance;</code></pre></div> Not okay: <div class="sourceCode" id="cb22"><pre class="sourceCode c"><code class="sourceCode c"><a href="#cb22-1" aria-hidden="true" tabindex="-1"></a>typedef struct { <a href="#cb22-2" aria-hidden="true" tabindex="-1"></a> void *wrong; <a href="#cb22-3" aria-hidden="true" tabindex="-1"></a> size_t way_to_write; <a href="#cb22-4" aria-hidden="true" tabindex="-1"></a>} something; <a href="#cb22-5" aria-hidden="true" tabindex="-1"></a>something instance;</code></pre></div> </div> </div> </body> </html>