Coding-Standard

[-[RiDER]-]

Der Autor Klaus Schmaranz hat sich die Mühe gemacht, die Semantik der Sprache C zu standardisieren. Ich lege wirklich allen nah, sich an diesen Standard zu halten, da er das Lesen von (fremden bzw. eigenen alten) Source-Codes wirklich erheblich erleichtert! Spätestens, wenn man im Team arbeitet, ist solch ein Standard unumgänglich.

Generelle Regeln
Die folgenden Prinzipien verbessern die Lesbarkeit und Wartbarkeit eines Programms sehr stark:

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.

Coding-Rules
Die hier angeführten Regeln helfen, den Source-Code so weit wie möglich zu vereinheitlichen und damit die Arbeit im Team zu erleichtern:

• 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:

  // 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:

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

    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.

Das Buch, in dem dieser "Coding-Standard" definiert wird:

Softwareentwicklung in C (von Klaus Schmaranz, 408 Seiten)
Verlag: Springer, Berlin; Auflage: 1 (September 2001)
ISBN-10: 3540419586
ISBN-13: 9783540419587

Ich kann das Buch übrigens nur empfehlen! Es eignet sich sowohl für Anfänger, als auch für Fortgeschrittene.

MfG RiDER

/*noctem: Ich habe mir erlaubt den Thread Sticky zu machen. */

[Nemo.A]

Hallo -[RiDER]-,
Habe früher mal nach sowas gesucht. Danke dir fürs reinstellen.
Werde mich sicher daran halten

[blackberry]

Zum Thema // in C...
Im ANSI-Standart sind // doch noch nicht als Kommentarbezeichner eingeführt, oder irre ich mich da?

Test:

#include <stdio.h>


int main(void)
{
	// comment
	return 0;
}

In der Konsole:

blackberry@system:~/Desktop$ gcc -ansi a.c -o a
a.c: In function ‘main’:
a.c:6: error: expected expression before ‘/’ token
blackberry@system:~/Desktop$ ls
a.c
blackberry@system:~/Desktop$ gcc -std=c99 a.c -o a
blackberry@system:~/Desktop$ ls
a  a.c

[-[RiDER]-]

Hi

Zum Thema // in C...
Im ANSI-Standart sind // doch noch nicht als Kommentarbezeichner eingeführt, oder irre ich mich da?

Ja, da hast Du Recht.
Diese Zeilenkommentare werden auch "C++-Stil-Kommentare" (probier mal -pedantic anstelle von -ansi) genannt, eben weil sie erst mit C99 eingeführt wurden und von C++ abgekuckt wurden.

In dieser Hinsicht (und eigentlich auch in jeder anderen) ist C99 also C89 vorzuziehen, da sich Zeilenkommentare zum Kommentieren von Kode besser eigenen als Blockkommentare - allein schon aus dem Grund, dass sich Blockkommentare nicht verschachteln lassen und somit das Auskommentieren von kommentiertem Kode unmöglich machen.

GreetZ RiDER

[Darkthief]

Cool, viele Sachen dabei die ich noch nicht wusste.
Mit wievielen Leerzeichen rückt man jetzt Funktions-, Schleifenblöcke etc. ein, auch mit 2?

[-[RiDER]-]

Hi

Mit wievielen Leerzeichen rückt man jetzt Funktions-, Schleifenblöcke etc. ein, auch mit 2?

Jopp.

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.

GreetZ RiDER

[rand]

_CapitalizedMitUnderlinesZuBeginnUndEnde_

Das ist ungünstig. Namen, die mit einem Unterstrich gefolgt von einem Großbuchstaben anfangen, sind reserviert. Siehe z.B. http://publib.boulder.ibm.com/infoce.../ref/ident.htm, Abschnitt "Reserved identifiers".

Ansonsten finde die Regeln ganz gut, auch wenn mir manches etwas zu restriktiv erscheint (ich bevorzuge z.B. 4 Leerzeichen und mag camelCase nicht).

[-[RiDER]-]

Namen, die mit einem Unterstrich gefolgt von einem Großbuchstaben anfangen, sind reserviert.

Das ist Quatsch.
Vllt. machen das manche Compiler, der Standard schreibt es aber definitiv nicht vor!

(ich bevorzuge z.B. 4 Leerzeichen und mag camelCase nicht).

Mit "4 Leerzeichen" meinst Du sicher die Breite der Einrückung. Ja, da gehen die Geschmäcker auseinander. Hauptsache ist, dass man im Team einheitlichen Einrückstil hat!

Tabs werden oft bevorzugt, da man im Editor ihre (angezeigte) Breite festlegen kann. Bei makefiles und in Python bleibt einem dabei garkeine Wahl, da muss man Tabs benutzen. C ist das egal, in Team sollte mans halt einheitlich machen (entweder alle Tabs, oder alle 2 Leerzeichen, oder alle 4 Leerzeichen usw.).

Und CamelCase finde ich auch oft unschön. Hat sich aber erstaunlich stark eingebürgert. Auch hier gilt: Im Team Haupsache einheitlicher Stil, wie der genau aussieht, kann ja vom OP abweichen, ist nur ein Vorschlag aus dem Buch und vieles davon ist nützlich und kann übernommen werden, ohne dass man sich selbst was ausdenken muss.

GreetZ RiDER

[rand]

Das ist Quatsch.
Vllt. machen das manche Compiler, der Standard schreibt es aber definitiv nicht vor!

Hab jetzt leider auf die Schnelle den Standard nicht online gefunden, nur einen Draft, aber die sollten sich in dem Punkt nicht unterscheiden.

All identifiers that begin with an underscore and either an uppercase letter or another
underscore are always reserved for any use.

(nicht ohne Grund heißen z.B. die neuen C99-Typen _Bool und _Complex).

Also bleibe ich dabei, die Strukturbezeichnungen sind ungünstig.

Bei dem Rest hast du aber Recht, das wichtigste ist Einheitlichkeit im Proramm.

[-[RiDER]-]

Hab jetzt leider auf die Schnelle den Standard nicht online gefunden, nur einen Draft, aber die sollten sich in dem Punkt nicht unterscheiden.

All identifiers that begin with an underscore and either an uppercase letter or another
underscore are always reserved for any use.

Tatsächlich, Du scheinst Recht zu haben: Bezeichner (und typedefed Types sind solche identifier), die mit Unterstrich beginnen, dem ein Großbuchstabe oder ein weiterer Unterstrich folgt, sind für die Standardbibliothek reserviert.

(nicht ohne Grund heißen z.B. die neuen C99-Typen _Bool und _Complex).

Gut, das wären zwei Schlüsselwörter - daraus ließe sich keine Regel ableiten (so wie uint64_t kein Schlüsselwort ist und dennoch als Bezeichner ausscheidet, da er Teil der Standardbibliothek ist).

Also bleibe ich dabei, die Strukturbezeichnungen sind ungünstig.

Sehr richtig, sehe ich jetzt auch so!
Die meisten Compiler werden derartige Bezeichner zulassen, der Standard schreibt aber undefined behavior vor und nach dem muss man sich wohl richten, wenn man nicht einen konkreten Compiler diskutiert.

Vllt. sollte man dem Verlag oder Autoren schreiben - von Donald E. Knuth jedenfalls würde man dafür 16^2 Cent kriegen

GreetZ RiDER