Coding-Standard

Einfachheit:

• Das Prinzip der Einfachheit ist auch als das KISS-Prinzip (Keep It Small and Simple) bekannt. Kurz gesagt sollen Funktionen genau eine, für ihren Abstraktionslevel adäquate, atomare Aufgabe erfüllen. Niemals sollen Funktionen mehrere Aufgaben auf einmal erfüllen, genauso wenig, wie sie Aufgaben erfüllen sollen, die in einen anderen Abstraktionslevel gehören (=Durchgriff nach unten oder oben). Die Parameterlisten von Funktionen sollen so kurz und übersichtlich wie möglich gehalten werden. Funktionen selbst sollen als Faustregel niemals mehr als 60 Zeilen lang sein. Eine durchschnittliche Länge von ca. 30 Zeilen ist zu bevorzugen.

Intuitivität:

• Das Prinzip der Intuitivität bedeutet, dass man den geschriebenen Source-Code „wie ein Buch“ lesen und verstehen können muss, und zwar ohne Kommentare im Source-Code und ohne Erklärungen des Programmierers! Damit ist impliziert, dass Variablen- und Funktionsnamen sprechend sein und genau ihrer Funktionalität entsprechend benannt sein müssen. Einbuchstabenvariablen, wie z.B. i, sind nicht erlaubt. Unnötige Kommentare werden als störend erachtet und sollen dementsprechend weggelassen werden. Ein typisches Beispiel für solche unnötigen Kommentare wäre:
  count++; // and here the counter is incremented

Einheitlichkeit:

• Verwandte Teile im Source-Code müssen denselben Prinzipien folgen. Z.B. wenn eine Funktion copy als ersten Parameter die Destination und als zweiten Parameter den Source nimmt, dann müssen verwandte Funktionen, wie z.B. move, sich an dieselben Konventionen halten. Genauso gilt dies z.B. in einer struct für einen Knoten. Wenn für diesen in der Implementation einer einfach verketteten Liste der Pointer auf das nächste Element unter dem Namen next ansprechbar ist, dann darf er nicht in einem Knoten für eine doppelt verkettete Liste auf einmal z.B. successor heißen.

• Die Sprache für Source-Code ist Englisch. Dies gilt für alle Teile eines Programms, von Variablennamen über Funktionsnamen bis zu Kommentaren im Source-Code.

• Der gebrauch von Block-Kommentaren (/* comment */) ist zu vermeiden.
  Stattdessen müssen Zeilenkommentare (// comment) eingesetzt werden.
  Dies macht Source-Code robuster gegen Änderungen und erleichtert
  das Debugging.

• Wenn es sich nicht vermeiden lässt z.B. algorithmische Details in Form von Kommentaren in den Source-Code einzubringen, dann ist ein Block mit einer vollständigen Erklärung des Algorithmus vor der Implementation des Algorithmus selbst zu schreiben. Es darf die Kommentierung des Algorithmus nicht im laufenden Source-Code Zeile für Zeile erfolgen, denn sonst wird der Code durch die Kommentare unleserlich.

• Sollten jemals Codezeilen in das Programm Eingang finden, bei denen beim Lesen der Zeile nicht sofort klar ist, was sie tut, dann muss dies in einem kurzen Kommentar dort festgehalten werden. Jedoch sollte man sich immer sehr gut überlegen, ob es nicht eigentlich ein besseres, leichter lesbares Konstrukt gibt, das keinen Kommentar braucht.

• Globale Variablen sind nach allen Möglichkeiten zu vermeiden.

• Wenn aus irgendwelchen Gründen böse Hacks im Source-Code nicht vermeidbar sind (z.B. Zeitdruck), so sind diese unbedingt in hack-start und hack-end Kommentare zu fassen, damit man sie einfach wieder finden und ausbessern kann. Die hack-…Kommentare haben die folgende Form:
  Code:

  // FIXXME (<author, date>) -> <description of the hack>
    [..... the code with the hack .....]
  // END FIXXME (<author, date>)

  Hier gehört das Keyword FIXXME immer mit zumindest zwei ‚X‘ geschrieben, denn damit kann man leicht nach ihm suchen. Je nachdem, wie schlimm der Hack ist, können auch mehrere ‚X‘ vorkommen. Als Faustregel für die Abstufung gilt, dass der SVH (=Schlimmste Vorstellbare Hack) mit 5 ‚X‘ geschrieben wird.

• Namen von Bezeichnern müssen den folgenden Konventionen genügen:
  • Funktionen: erstesWortKleinRestCapitalizedOhneUnderlines
  • Konstanten: GROSS_MIT_UNDERLINES
  • Lokale Variablen: klein_mit_underlines
  • Globale Variablen: klein_mit_underlines_und_underline_am_ende_
  • Structures: _CapitalizedMitUnderlinesZuBeginnUndEnde_
    • Diese dürfen nicht direkt verwendet werden, sondern nur über ein typedef (=typedef’ed Structures)!
  • typedef’ed Structures: DurchgehendCapitalizedOhneUnderlines
  • Unions: _CapitalizedMitUnderlinesZuBeginnUndEnde_
    • Diese dürfen nicht direkt verwendet werden, sondern nur über ein typedef (=typedef’ed Unions)!
  • typedef’ed Unions: DurchgehendCapitalizedOhneUnderlines

• Die Struktur des Source-Codes muss den folgenden Prinzipien genügen:
  • Jedes File muss einen Header besitzen, in dem zumindest der Filename, und eine kurze Beschreibung des Inhalts zu finden sind. In der Praxis hat es sich eingebürgert, dass weiters der Name des Autors, das Erstellungsdatum, das letzte Änderungsdatum, eine Versionsnummer und ein Copyright-Statement im Header stehen.
  • Geschwungene Klammern für Code-Blöcke müssen in einer eigenen Zeile stehen. Die Einrückung der Klammern entspricht genau dem umschließenden Block. Der eingeschlossene Block selbst muss genau um 2 Spaces eingerückt sein. Einrückungen dürfen ausschließlich mit Spaces gemacht werden, Tabs sind verboten, denn sonst kann es mit verschiedenen Editor-Einstellungen und beim Drucken Probleme geben.
  • Vor jeder Funktionsdefinition muss eine Linie der folgenden Form stehen, damit eine Funktion beim Lesen des Source-Codes visuell hervorsticht:
    Code:

    //--------------------------------------------------

    Diese Linie soll in der Regel mit 60-70 ‚-‚ geschrieben werden.

  • Zwischen dieser Linie und dem Header der Funktion muss in kurzen Worten beschrieben werden, wozu diese Funktion dient. Bei größeren Projekten muss auch beschrieben sein, was bei den einzelnen Parametern erwartet wird, welche Randbedingungen gelten, welche Return-Values zu erwarten sind und wie diese zu interpretieren sind.