Update 'Coding Style'

Coding-Style.md

@@ -43,7 +43,7 @@ Keep the length of source code lines to 100 characters or less to ensure maximum
 Each new level is indented by 2 spaces, braces go on a line by themselves, and they are indented as well:
 
 ```c
-while ((c = *str++))
+while (c = *str++)
   {
     if ((c >= 97) && (c <= 122))
       {
@@ -61,41 +61,41 @@ Continuation lines should align wrapped elements with the first argument (exclud
 #### Aligned Along First Deliminator
 ```c
 # Correct
-error = initialize_tagtree(&prec_control->tag_inclusion,
+error = initialize_tagtree (&prec_control->tag_inclusion,
                              prec_control->numCbX,
                              prec_control->numCbY,
                              prec_control->numCbZ,
                              prec_control->numCbTS)
-exit(error);
+exit (error);
 
 # Wrong
-error = initialize_tagtree(&prec_control->tag_inclusion,
+error = initialize_tagtree (&prec_control->tag_inclusion,
                             prec_control->numCbX,
                             prec_control->numCbY,
                             prec_control->numCbZ,
                             prec_control->numCbTS)
-exit(error);
+exit (error);
 ```
 
 #### Hanging Indent
 ```c
 # Correct
-error = initialize_tagtree(
+error = initialize_tagtree (
           &prec_control->tag_inclusion,
            prec_control->numCbX,
            prec_control->numCbY,
            prec_control->numCbZ,
            prec_control->numCbTS);
-exit(error);
+exit (error);
 
 # Wrong
-error = initialize_tagtree(
+error = initialize_tagtree (
   &prec_control->tag_inclusion,
    prec_control->numCbX,
    prec_control->numCbY,
    prec_control->numCbZ,
    prec_control->numCbTS);
-exit(error);
+exit (error);
 ```
 
 ### Braces
@@ -104,9 +104,9 @@ Curly braces for function definitions should rest on a new line and should not a
 
 ```c
 uint64
-bytes_used(bwc_stream const *const stream)
+bytes_used (bwc_stream const *const stream)
 {
-  if(stream->T == 0xFF)
+  if (stream->T == 0xFF)
       return stream->L + 1;
   else
       return stream->L;
@@ -117,7 +117,7 @@ A new block should always be placed on a new indentation level:
 ```c
 f = fopen('file');
 {
-  if(stream->T == 0xFF)
+  if (stream->T == 0xFF)
       return stream->L + 1;
   else
       return stream->L;
@@ -128,40 +128,182 @@ fclose(f);
 Curly braces should not be used for single statement blocks
 
 ```c
-if(stream->T == 0xFF)
+if (stream->T == 0xFF)
     return stream->L + 1;
 else
     return stream->L;
 ```
 unless one of the following 4 exceptions applies:
 
-1. If either side of an if…else statement has braces
+**1.** If either side of an if…else statement has braces
 ```c
-if(stream->T == 0xFF)
+if (stream->T == 0xFF)
+  {
+    stream->L = stream->L + stream->t
     return stream->L + 1;
+  }
 else
+  {
     return stream->L;
+  }
 ```
-2. If a single statement covers multiple lines
+**2.** If a single statement covers multiple lines
 ```c
+if (stream->T == 0xFF)
+  {
+    stream->L = stream->L 
+              + stream->Lmax
+              + stream->t;
+  }
+else
+  {
+    return stream->L;
+  }
 ```
-3. If the condition is composed of many lines
+**3.** If the condition is composed of many lines
 ```c
+if (stream->L <= stream->Lmax
+    stream->T == 0xFF &&
+    stream->t == 8)
+  {
+    return stream->L + 1;
+  }
+else
+  {
+    return stream->L;
+  }
 ```
-4. Nested if, in which case the block should be placed on the outermost if
+**4.** Nested if, in which case the block should be placed on the outermost if
 ```c
+if (stream->L <= stream->Lmax)
+  {
+    if (stream->T == 0xFF)
+      return stream->L + 1;
+    else
+      return stream->L;
+  }
+else
+  {
+    stream->L++;
+  }
 ```
+The closing parenthesis in multiline constructs must be placed at the end of the last line of the construct, as in:
 
+```c
+# Correct
+DWT_5X3_FILTER[2][5]  = {{DWT_5X3_H1,  DWT_5X3_H0,  0,          0, 0}, 
+                         {DWT_5X3_G2,  DWT_5X3_G1,  DWT_5X3_G0, 0, 0}};
+```
 
 ### Whitespace
+Always put a space before an opening parenthesis but never after. For multiple opening parenthesis only a single space in front of the first parenthesis should be used:
 
 ```c
-prec_control->numCodeblocks_a = (uint64)(prec_control->numCbX
+while (c = *str++)
+  {
+    if ((c >= 97) && (c <= 122))
+      {
+        c = c - 32;
+      }
+    hash = (hash * 33) ^ c;
+  }
+
+# Wrong
+while(c = *str++)
+  {
+    if((c >= 97) && (c <= 122))
+      {
+        c = c - 32;
+      }
+    hash =(hash * 33) ^ c;
+  }
+  
+# Wrong
+while (c = *str++)
+  {
+    if ( (c >= 97) && (c <= 122))
+      {
+        c = c - 32;
+      }
+    hash = (hash * 33) ^ c;
+  }
+```
+
+When declaring a structure type use newlines to separate logical sections of the structure:
+
+```c
+  typedef struct
+  {
+    uint16                      CSsgc;                    // Flag signaling user control variable.
+    uchar                       resilience;               // Flag signalling error resilience.
+
+    uint64                      tileSizeX,  tileSizeY;    // Spatial tile size.
+    uint64                      tileSizeZ,  tileSizeTS;   // Temporal tile size.
+
+    uint64                      numTilesX,  numTilesY;    // Spatial number of tiles.
+    uint64                      numTilesZ,  numTilesTS;   // Temporal number of tiles.
+    uint64                      numTiles;                 // Global number of tiles.
+    ⋮
+  } bwc_gl_ctrl;
+```
+Do not eliminate whitespace and newlines just because something would fit on a single line:
+
+```c
+# Wrong
+if (stream->T == 0xFF) return stream->L + 1; else return stream->L;
+```
+
+Do eliminate trailing whitespace on any line, preferably as a separate patch or commit. Never use empty lines at the beginning or at the end of a file.
+
+### Functions
+The following general rules should be followed when defining a function in BigWhoop:
+* Function name must be lowercase, optionally separated with underscore _ character
+* Functions private to a translation unit need to be declared before they are called
+* All private functions of a translation unit must appear before the public functions in their respective block, which is identified by the block header 'private functions':
+* All public functions must appear in their respective block, identified by the `public functions` block header, following the `private functions` block:
+
+
+
+
+Functions should be declared by placing the returned value on a separate line from the function name:
+```c
+static void
+free_tile (bwc_field *const field)
+{
+  ⋮
+}
+```
+The argument list must be broken into a new line for each argument, with the argument names right aligned, taking into account pointers and const qualifiers:
+```c
+static uchar
+initialize_subband (bwc_field            *const  field, 
+                    bwc_parameter        *const  parameter,
+                    bwc_resolution       *const  resolution,
+                    bwc_subband          *const  subband, 
+                    int32          const         level, 
+                    int16          const         highband)
+{
+  ⋮
+}
+```
+
+This alignment holds when calling the function:
+ ```c
+initialize_subband (field,
+                    parameter, 
+                    resolution, 
+                    &resolution->subband[m], 
+                    r, 
+                    l);
+```
+
+
+```c
+prec_control->numCodeblocks_a = (uint64) (prec_control->numCbX
                                         * prec_control->numCbY
                                         * prec_control->numCbZ
                                         * prec_control->numCbTS);
 ```
-### Functions
 ### Derived Types
 
 ## Comments