TOPIO/BigWhoop
TOPIO/BigWhoop
4
1
Fork 0
Code Issues 26 Pull requests 1 Projects 6 Releases Packages Wiki Activity

Update 'Coding Style'

Patrick Vogler 2023-06-22 13:37:57 +00:00
parent 116fb27c49
commit 476b54c903
1 changed files with 175 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

208
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: Each new level is indented by 2 spaces, braces go on a line by themselves, and they are indented as well:
```c ```c
while ((c = *str++)) while (c = *str++)
{ {
if ((c >= 97) && (c <= 122)) if ((c >= 97) && (c <= 122))
{ {
@ -61,41 +61,41 @@ Continuation lines should align wrapped elements with the first argument (exclud
#### Aligned Along First Deliminator #### Aligned Along First Deliminator
```c ```c
# Correct # 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->numCbX,
prec_control->numCbY, prec_control->numCbY,
prec_control->numCbZ, prec_control->numCbZ,
prec_control->numCbTS) 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);
``` ```
#### Hanging Indent #### Hanging Indent
```c ```c
# Correct # Correct
error = initialize_tagtree( error = initialize_tagtree (
&prec_control->tag_inclusion, &prec_control->tag_inclusion,
prec_control->numCbX, prec_control->numCbX,
prec_control->numCbY, prec_control->numCbY,
prec_control->numCbZ, prec_control->numCbZ,
prec_control->numCbTS); prec_control->numCbTS);
exit(error); exit (error);
# Wrong # Wrong
error = initialize_tagtree( error = initialize_tagtree (
&prec_control->tag_inclusion, &prec_control->tag_inclusion,
prec_control->numCbX, prec_control->numCbX,
prec_control->numCbY, prec_control->numCbY,
prec_control->numCbZ, prec_control->numCbZ,
prec_control->numCbTS); prec_control->numCbTS);
exit(error); exit (error);
``` ```
### Braces ### Braces
@ -104,9 +104,9 @@ Curly braces for function definitions should rest on a new line and should not a
```c ```c
uint64 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; return stream->L + 1;
else else
return stream->L; return stream->L;
@ -117,7 +117,7 @@ A new block should always be placed on a new indentation level:
```c ```c
f = fopen('file'); f = fopen('file');
{ {
if(stream->T == 0xFF) if (stream->T == 0xFF)
return stream->L + 1; return stream->L + 1;
else else
return stream->L; return stream->L;
@ -128,40 +128,182 @@ fclose(f);
Curly braces should not be used for single statement blocks Curly braces should not be used for single statement blocks
```c ```c
if(stream->T == 0xFF) if (stream->T == 0xFF)
return stream->L + 1; return stream->L + 1;
else else
return stream->L; return stream->L;
``` ```
unless one of the following 4 exceptions applies: 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 ```c
if(stream->T == 0xFF) if (stream->T == 0xFF)
{
stream->L = stream->L + stream->t
return stream->L + 1; return stream->L + 1;
}
else else
{
return stream->L; return stream->L;
}
``` ```
2. If a single statement covers multiple lines **2.** If a single statement covers multiple lines
```c ```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 ```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 ```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 ### 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 ```c
prec_control->numCodeblocks_a = (uint64)(prec_control->numCbX while (c = *str++)
* prec_control->numCbY {
* prec_control->numCbZ if ((c >= 97) && (c <= 122))
* prec_control->numCbTS); {
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 ### 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 ### Derived Types
## Comments ## Comments