aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/CODE_STYLE.md84
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