From 27c2131b027710866c2124d6723c19a9f1cc06f4 Mon Sep 17 00:00:00 2001
From: Jay Satiro <raysatiro@yahoo.com>
Date: Sun, 11 Sep 2016 19:12:14 -0400
Subject: CODE_STYLE: add column alignment section

Note that since the added examples are for column alignment I had to
encapsulate with ~~~c markdown to preserve their alignment.
---
 docs/CODE_STYLE.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 53 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/CODE_STYLE.md b/docs/CODE_STYLE.md
index 73a4d94b7..d92d91662 100644
--- a/docs/CODE_STYLE.md
+++ b/docs/CODE_STYLE.md
@@ -72,8 +72,12 @@ the initial keyword. Like this:
       /* clearly a youngster */
     }
 
-When we write functions however, the opening brace should be in the first
-column of the first line:
+You may omit the braces if they would contain only a one-line statement:
+
+    if(!x)
+      continue;
+
+For functions the opening brace should be on a separate line:
 
     int main(int argc, char **argv)
     {
@@ -162,6 +166,53 @@ Examples:
     complement = ~bits;
     empty = (!*string) ? TRUE : FALSE;
 
+## 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
+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:
+
+~~~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;
+~~~
+
+~~~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));
+~~~
+
 ## Platform dependent code
 
 Use `#ifdef HAVE_FEATURE` to do conditional code. We avoid checking for
-- 
cgit v1.2.3