Peter: 1 Version importiert

2023-10-31T08:03:08Z

1 Version importiert

← Nächstältere Version	Version vom 31. Oktober 2023, 10:03 Uhr
(kein Unterschied)

en>Peter: 1 Version importiert

2023-08-22T19:35:50Z

1 Version importiert

Neue Seite

== Scope ==
[[File:Blacksheep320x240.jpg|right]]This page contains naming, structure and design rules for writing <code>C code</code> at BLACKSheep® OS for Blackfin® processors.

== Naming of identifiers ==
Every identifier has to be named in English.

The first character of an identifier must not contain underscores (there are some compiler directives which start with underscores and this could lead to conflicts)!

=== Variables ===
* Mixed case letters has to be used and the appropriate prefixes have to be inserted where necessary.
* Variable names have to be self explanatory. The names have to be provided with the appropriate prefixes and they have to start with an uppercase letter. In case of combining prefixes, the use of ranges/arrays/pointer/enumerations/structures is at first, followed by basic data types or object prefixes.
* The only exception are loop variables (thereby the use of i, j, k is allowed).
* Only one variable declaration per line is allowed
* Pointer operators at the declaration have to be located in front of the variable (not after the type identifier).
* If possible Initializations have to be done directly at the declaration.
 
;Prefixes for ranges/arrays/pointer/enumerations/structures
{| class="wikitable"
|-
! Prefix!! Description
|-
| <code>g_</code> || For global varaibles.
|-
| <code>s_</code> || For static variables.
|-
| <code>pa_</code> || For function parameters.
|-
| <code>a</code> || For arrays.
|-
| <code>fn</code> || For function pointers.
|-
| <code>p</code> || For pointers.
|-
| <code>t</code> || For self definend datatypes e.g. enumerations, structures.
|-
| <code>h</code> || For handlers.
|}
 
;Prefixes for basic data types
{| class="wikitable"
|-
! Prefix!! Description
|-
| <code>c</code> || For characters (8Bit).
|-
| <code>b</code> || For boolean (1Bit).
|-
| <code>n</code> || For datatype: int (32Bit) and long (32Bit).
|-
| <code>f</code> || For all kind of floating point datatypes.
|-
| <code>s</code> || For short(16Bit).
|-
| <code>ll</code> || For long long (64Bit).
|-
| <code>u</code> || Additional prefix to indicate an unsigned variable.
|}

 
; Prefixes for basic global variables
For global variables the prefix <code>g_</code> should be used, followed by the type prefix.

==== Example ====
<source lang="c">
bool g_bIsInitialized;
void aFunction (int pa_nParameter) {
int nNumber;
int *pnNumber = &nNumber;
char cKey;
float fPi = 3.1415;
int anNumbers[10];
unsigned char * pucPac;
}
</source>

=== Datatypes ===
Defining your own datatypes is common and necessary to improve code readability. 
The notation for self defined datatypes is: <source lang="c">T_TYPE_DESCRIPTION</source>
; Example
<source lang="c">
typedef unsigned long T_UART_HANDLE;

typedef struct _EXAMPLE_CFG {
bool bDTParalell;
unsigned long unIVG;
unsigned long unPPIerrIVG;
unsigned long unDMAerrIVG;
} T_EXAMPLE_CFG;
</source>

=== Blocks ===
The left parenthesis of a block has to be in the same line as the starting construct. 
The right parenthesis has to be in an own line.
The parenthesis must '''ALWAYS''' be used! Also in single ''for'' or ''if'' statements!
; ''Never'' type something like this
<source lang="c">
if (x == 1) y = 10;
</source>
or this:
<source lang="c">
if (x==1)
y=10;
</source>
==== BLACKSheep® conform notation ====
; if /else statements
<source lang="c">
if (...) {
...
} else if (...) {
...
} else {
...
}
</source>

; For statements
<source lang="c">
for (...) {
...
}
</source>

; Switch/case statements
<source lang="c">
switch (nVariable) {
case 0 : {
...
break;
}
case 1 : {
...
break;
}
default : {
...
}
}
</source>

=== Functions ===
Functions should start with a three or four letter identifier common for all functions in a c-file. 
The letters should be in upper case.

The left parenthesis of the function has to be in the same line as the last parameter and the close bracket.
; Example
<source lang="c">
T_ERROR_CODE UARTwriteByte(T_UART_HANDLE pa_tHndl, unsigned char pa_ucValue) {
...
}

</source>
If the number of parameters is too long to fit in one line the function declaration should be formatted as follow:
<source lang="c">
T_ERROR_CODE UARTsetMode ( unsigned long pa_unBaudrate,
unsigned char pa_ucStopBits,
unsigned char pa_ucParity ) {
...
}
</source>

=== Error codes ===
If the function returns an error code the T_ERROR_CODE declaration should be used (declared in “'''driver/include/datatypes.h'''”). 
A generic error type called ERR_GENERIC is already defined there.
The “driver/include” path must be added to the project options as a standard include path.
All error values should be derived from ERR_GENERIC.
; Example
<source lang="c">
#include <datatypes.h>
#define UART_ERR_RX_BUFFER_FULL (ERR_GENERIC – 10)
</source>

=== Include guards ===
The use of include guards is recommended. If used, they have to look like this:
<source lang="c">
#ifndef _SAMPLE_H_INCLUDED_
#define _SAMPLE_H_INCLUDED_
...
#endif
</source>

=== Include paths ===
Include paths has to be relative. '''Don’t use absolute paths'''! 
Use slashes as directory separator. '''Don’t use backslash'''!
; Example
<source lang="c">
#include “../vdm/vdmconfig.h”
</source>
Include files from standard include directories (VDSP++ as well as BLACKSheep) has to be declared as follow:
<source lang="c">
#include <stdio.h>
</source>
Standard include directories for BLACKSheep are:
* Driver/ include
* Blacksheep/include
Both directories should be added as standard include directories on all VDSP++ projects.

=== Macros ===

Macro should be in '''capital letters''' and''' self explaining.''' 
Macros should start with a three or four byte identifier related to the c-file or the function block. 
As separator use the underline character.
; Example
<source lang="c">
#define UART_PARITY_NONE 0
</source>

=== Indentation ===
The tabulator width has to be set to four. '''Instead''' of tabulator ''characters spaces'' have to be inserted (usually there is an option for this in the IDE). 
In VDSP++: {{mp|Settings|Prefernces|Editor Tab}}. 
A new block has to be started at the same line as its initial statement.

=== Comments ===
A sufficient amount of comments have to be written. 
'''There are never too many comments, whereas invalid comments are worse than none''' – thus '''invalid comments''' have to be removed from the source code. 

Comments have to be written in English. It is allowed to indicate Single-line comments with // ahead of the command or in the same line right after the command. All other comments have to be located ahead of the command or block.

Generally comments have to be tagged with '''//''' or the doxygen style '''///< not /*…*/ to allow the temporarily commenting out of code with /* … */!'''

Comments have to be meaningful, to describe to program and to be up to date.

All c- and h-files in addition must have '''doxygen compatible''' comments as described [[BLACKSheep® Doxygen Guideline| here]].

BLACKSheep® Coding Guideline - Versionsgeschichte

Peter: 1 Version importiert

en>Peter: 1 Version importiert