From Coding Standard
Jump to: navigation, search

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

Comments

Codelayout

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.