Return to CODE_STYLE.md CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs

curl

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