diff options
| -rw-r--r-- | docs/CODE_STYLE.md | 84 |
1 files changed, 46 insertions, 38 deletions
diff --git a/docs/CODE_STYLE.md b/docs/CODE_STYLE.md index ba5f71026..2d275cd7d 100644 --- a/docs/CODE_STYLE.md +++ b/docs/CODE_STYLE.md @@ -9,8 +9,8 @@ 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 -`lib/checksrc.pl` script. Invoked with `make checksrc` or even by default by -the build system when built after `./configure --enable-debug` has been used. +"lib/checksrc.pl" script. Invoked with "make checksrc" or even by default by +the build system when built after "./configure --enable-debug" 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 @@ -44,8 +44,8 @@ open brace. ## Comments -Since we write C89 code, `//` comments are not allowed. They weren't -introduced in the C standard until C99. We use only `/*` and `*/` comments: +Since we write C89 code, **//** comments are not allowed. They weren't +introduced in the C standard until C99. We use only **/* comments */**. /* this is a comment */ @@ -87,8 +87,8 @@ For functions the opening brace should be on a separate line: ## 'else' on the following line -When adding an `else` clause to a conditional expression using braces, we add -it on a new line after the closing brace. Like this: +When adding an **else** clause to a conditional expression using braces, we +add it on a new line after the closing brace. Like this: if(age < 40) { /* clearly a youngster */ @@ -149,8 +149,8 @@ and NEVER: ## Space around operators -Please use spaces on both sides of operators in C expressions. Postfix `(), -[], ->, ., ++, --` and Unary `+, - !, ~, &` operators excluded they should +Please use spaces on both sides of operators in C expressions. Postfix **(), +[], ->, ., ++, --** and Unary **+, - !, ~, &** operators excluded they should have no space. Examples: @@ -167,63 +167,71 @@ Examples: complement = ~bits; empty = (!*string) ? TRUE : FALSE; +## No parentheses for return values + +We use the 'return' statement without extra parentheses around the value: + + int works(void) + { + return TRUE; + } + +## Parentheses for sizeof arguments + +When using the sizeof operator in code, we prefer it to be written with +parentheses around its argument: + + int size = sizeof(int); + ## Column alignment -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 +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 will span 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's 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: +cases follow the 2-space indent guideline. Here are some examples from +libcurl: -~~~c if(Curl_pipeline_wanted(handle->multi, CURLPIPE_HTTP1) && (handle->set.httpversion != CURL_HTTP_VERSION_1_0) && (handle->set.httpreq == HTTPREQ_GET || handle->set.httpreq == HTTPREQ_HEAD)) /* didn't ask for HTTP/1.0 and a GET or HEAD */ return TRUE; -~~~ -~~~c - case CURLOPT_KEEP_SENDING_ON_ERROR: - data->set.http_keep_sending_on_error = (0 != va_arg(param, long)) ? - TRUE : FALSE; - break; -~~~ +If no parenthesis, use the default indent: -~~~c data->set.http_disable_hostname_check_before_authentication = (0 != va_arg(param, long)) ? TRUE : FALSE; -~~~ - -~~~c - if(option) { - result = parse_login_details(option, strlen(option), - (userp ? &user : NULL), - (passwdp ? &passwd : NULL), - NULL); - } -~~~ - -~~~c - DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing " - "server response left\n", - (int)clipamount)); -~~~ + +Function invoke with an open parenthesis: + + if(option) { + result = parse_login_details(option, strlen(option), + (userp ? &user : NULL), + (passwdp ? &passwd : NULL), + NULL); + } + +Align with the "current open" parenthesis: + + DEBUGF(infof(data, "Curl_pp_readresp_ %d bytes of trailing " + "server response left\n", + (int)clipamount)); ## Platform dependent code -Use `#ifdef HAVE_FEATURE` to do conditional code. We avoid checking for +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 config-[system].h 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 style where the `magic()` function works differently +seamless. Like this example where the **magic()** function works differently depending on a build-time conditional: #ifdef HAVE_MAGIC |