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
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.