Annotation of embedaddon/curl/docs/CODE_STYLE.md, revision 1.1
1.1 ! misho 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);
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to CODE_STYLE.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs