Embedded-C

This page shows the specific C/C++ coding standards, some of the stuff might not be applicable for either language, but should be seperated in a fairly intuitive way.
=Summary of the rules=
==General==
* The used language is Englisch.
* Code has to be consitently structured
* Naming Convention is compulsory
==Comments==
* Every file contains a commentheader
* Every function has a header
==Codelayout==
* Spaces between operators and parameters
* One Command per line
* Brackets have their own line
* Every block has to be indented
* 80 symbols per line
=Explanation of the rules=
==Code has to be consitently structured==
Der CodingStandard soll die Studierenden dazu verleiten, leserlichen und wartbaren Code zu schreiben, ohne sie mit zu vielen Regeln und Details belasten.
Daher ist klar, dass der CodingStandard bei Weitem nicht alle Eventualitäten abdeckt, und die LV-Leitung vertraut in den meisten Fällen auf den gesunden Menschenverstand der Studierenden.
Das Wichtige hierbei ist, auf Einheitlichkeit zu achten.
Prominentes Beispiel hierbei ist die Position des Pointersterns:
int original = 0;
int* first_original_pointer = &original; // Correct
int *second_original_pointer = &original; // Also correct
==Naming Convention==
Die Namenskonvention beschreibt die Formatierungsregeln für die verschiedenen Arten von Befehlen/Typen, die in einem Programm vorkommen können.
typedef‘ed Enums, Structs und Unions 	Capitalized_With_Underscores_And_Trailing_Underscore_
functions 	firstWordLowerCaseRestCapitalizedWithoutUnderscores
local variables, functionparameters 	all_lower_case_with_underscores
Iterators 	iterator_for_what
Struct-elements 	all_lower_case_with_underscores_and_trailing_underscore_
Constants, defines, Enum-Elements 	ALL_UPPERCASE_WITH_UNDERSCORES
Not typedef’ed Enums, Structs, Unions	_AllWordsCapitalizedWithUnderscoresOnBothEnds_
==Every file has a commentheader==
Am Anfang der Quelldatei (.c-Datei) gibt es einen Kommentarblock, der ein paar Informationen über sie liefert.
Der Headerkommentar hat folgendes Schema, der einfach kopiert und adaptiert werden soll:
//-----------------------------------------------------------------------------
// <Filename>.c
//
// <Explanation of the program ...>
// <... May have multiple lines.>
//
// Last changed: <Date>
// Author: <Name>
//
// History:
// <Date> .. initial content by <Name>
//-----------------------------------------------------------------------------
//
==Every function has a header==
Funktionen sind Herz und Seele eines C-Programms, und es ist (insbesondere für die Korrektur) unabdingbar, dass man leicht erkennt, welche Funktion was tut, ohne den Code erst lesen und verstehen zu müssen.
Diese Art von "Headerkommentaren" sind so weit verbreitet, dass es Tools gibt, die mit Hilfe dieser Header eine Dokumentation des Programms generieren können.
Damit das funktioniert, muss natürlich genau festgelegt sein, wie der Headerkommentar aussieht. Ein beliebtes Beispiel ist Doxygen (http://www.doxygen.org/).
//-----------------------------------------------------------------------------
///
/// This is an example header comment. Copypaste and adapt it!
///
/// Inputs:
/// @param human The human to check.
/// @param number_to_return_if_not_married The number to return if the human
/// is not married. Should be 0 or 1 for example purposes.
///
/// Outputs:
/// @return int age of spouse
//
int getAgeOfSpouse(Human* human, int number_to_return_if_not_married)
{
 ...
}
==Spaces between operators and parameters==
Zu Gunsten besserer Lesbarkeit sind bei binären Operanden (wie +, -, =, etc.) und Parametern Leerzeichen einzufügen.
int wrong=0; // wrong
int correct = wrong + 5; // correct
int *a_pointer = &wrong; // Unary operators don't need whitespaces
wrong = correct++; // This is ok as well
doSomething(wrong, correct, a_pointer); // Whitespaces after ","
==One Command per line==
Jedes Statement beginnt in einer neuen Zeile, ausgenommen sind natürlich verschachtelte Befehle innerhalb eines "größeren" Befehls.
Auch Variablendeklarationen sollen einzeln vorgenommen werden, und nicht "aneinandergekettet" (int a = 0, b = 1, c = 2).
Statt
int my_number = 1; char whatever = 'a'; if (my_number == 1) printf("test"); int a = 0, b = 1, c = 2;
ist also
int my_number = 1;
char whatever = 'a';
if (my_number == 1) 
 printf("test");
int a = 0;
int b = 1;
int c = 2;
zu schreiben.
Das gilt insbesondere auch für Switch-Cases:
switch (number)
{
 case 0: // Linebreak!
 a = 1; // do something
 break;
 default: // Linebreak!
 a = 2;
 break;
}
==Brackets have their own line==
Ausnahmen sind:
*Typedef's
*Strichpunkte
Blockklammern sind die geschwungenen Klammern ("{" und "}"), die zusammengehörende Codeteile (Blöcke) markieren.
Diese Regel dient einfach nur zur besseren Übersichtlichkeit, besonders bei verschachelten Schleifen und Verzweigungen.
Es müssen aber Ausnahmen gemacht werden, da die Regel sonst der Übersichtlichkeit mehr schadet als hilft:
Falsch	Richtig
typedef struct _Whatever_
{
 int whatever_;
} 
Whatever;	
typedef struct _Whatever_
{
 int whatever_;
} Whatever;
struct _Whatever_
{
 int whatever_;
}
;	
struct _Whatever_
{
 int whatever_;
};
==Every block has to be indented==
Every code block has to be indented, to achieve better readability of interleaved/complex code blocks.
int main()
{
 if (1 == 1)
 {
 if (2 == 2)
 {
 printf("OK this is good");
 }
 else
 {
 printf("This is kind of bad ...");
 }
 }
 return 0;
}
An example, why wrong indentions are a hazard, is that if/else statements and for/while loops expect code blocks, when there are no brackets surrounding the code block, only the next line of code counts for the statement.
int a = 1;
int b = 0;
if (a == 1)
 b = 1; // Will happen only if a == 1
 b = 2; // is NOT part of the if-block, will therefore be called regardless of a!
printf("%d", b); // b is always 2. 
==80 symbols per line==
Es ist
klar,
dass zu kurze 
Zeilen der 
Leserlichkeit eines 
Codes Schaden 
zufügen.
Es ist aber genau so schlecht, zu lange Zeilen zuzulassen. Nicht nur, dass manche Entwicker den Code zum Debuggen/Verstehen ausdrucken, es ist auch nicht unbedingt angenehm, am Monitor lange horizontal scrollen zu müssen, um Anfang und Ende einer Zeile lesen zu können. Wenn dieser Text bis hierher gelesen wurde, ist sicherlich einleuchtend, was gemeint ist.
80 symbols are a good compromose to either achieve readability and to be able to print the code.
If your code exceeds 80 symbols in a line, just contain after a line break with an indention and continue the code.