From 476b54c903aa349e9dea642b88b7f588799ace5d Mon Sep 17 00:00:00 2001 From: Patrick Vogler Date: Thu, 22 Jun 2023 13:37:57 +0000 Subject: [PATCH] Update 'Coding Style' --- Coding-Style.md | 208 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 175 insertions(+), 33 deletions(-) diff --git a/Coding-Style.md b/Coding-Style.md index 5e38400..81dbf49 100644 --- a/Coding-Style.md +++ b/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); + +# Wrong +error = initialize_tagtree (&prec_control->tag_inclusion, prec_control->numCbX, prec_control->numCbY, prec_control->numCbZ, prec_control->numCbTS) -exit(error); - -# Wrong -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( - &prec_control->tag_inclusion, - prec_control->numCbX, - prec_control->numCbY, - prec_control->numCbZ, - prec_control->numCbTS); -exit(error); +error = initialize_tagtree ( + &prec_control->tag_inclusion, + prec_control->numCbX, + prec_control->numCbY, + prec_control->numCbZ, + prec_control->numCbTS); +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 - * prec_control->numCbY - * prec_control->numCbZ - * prec_control->numCbTS); +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); +``` ### Derived Types ## Comments