Index Referenz Richtlinien Bemerkungen

Programmerrichtlinien

Die Bibliothek entwickeln mehrere Personen unabhängig voneinander. Damit es nicht zu unnötigen Problemen kommt, wie etwa Namenskonflikte, sind ein paar Regeln einzuhalten. Diese Regeln betreffen:

Namensgebung
Kommentare
Globale Typen, Konstanten etc.
Ausnahmen und Ausnahmebehandlung
Ausgabeoperator <<

Namensgebung

Element	Richtlinie	Beispiel
class, struct	Namen bestehen aus Groß- und Kleinbuchstaben und enthalten keine Unterstriche. Alle Namen fangen mit einem Großbuchstaben an.	`class AudioCache { };` `class Complex { };`
typedef	s.o.	`typedef int Sample;` `typedef unsigned char Byte;` `typedef LinearFFT<double> SimplyFFT;`
enum	s.o.	`enum SeekMode { BEG = 0, CUR, END };`
const	Namen werden mit Großbuchstaben geschrieben. Worte werden durch Unterstriche voneinander getrennt.	`const int MIN_WINDOW_SIZE = 16;` `const int MAX_LENGTH = 1000;`
Funktionen	Namen bestehen aus Groß- und Kleinbuchstaben und enthalten keine Unterstriche. Alle Namen fangen mit einem Kleinbuchstaben an.	`void load(int samples) const;` `int samplesAbove(const AudioCache& cache, Sample x);`
Variablen	Namen bestehen aus Groß- und Kleinbuchstaben und enthalten keine Unterstriche. Alle Namen fangen mit einem Kleinbuchstaben an.	`int windowSize = 0;` `vector<Sample> samples;`

Es ist zu beachten: Namen, die mit einem Unterstrich gefolgt von einem Großbuchstaben anfangen, sind in C++ reserviert (etwa _Default_Device).

Es hat sich bewehrt, Felder mit Worten in Plural zu benennen (z.B. samples oder amplitudes). Funktionen, die einen Wert von Typ bool zurückliefern, sollten möglichst einen Verb wie "is" oder "has" in ihrem Namen haben, z.B.: isOpen() statt open().

Kommentare

Kommentare, die etwas über die Verwendung einer Klasse oder Funktion sagen, sollten in Header-Dateien stehen. Kommentare zur Implementation sollten sich dagegen in den Programmdateien (*.cpp o.ä.) befinden.

Mit docpp kann die Programmdokumentation automatisch erzeugt werden. Die Kommentare in Header-Dateien sollten sich deshalb an den Syntaxregeln von docpp orientieren. Hier ein Beispiel:

So könnten die Kommentare in der Header-Datei einer Klasse AudioData aussehen:

/**
* Die Klasse stellt eine Audiodatei dar. Sie bietet eine
* Reihe von Methoden zum Öffnen, Lesen und Schliessen
* von Audiodateien usw.
*
* @memo stellt eine Audiodatei dar
*
* @author Silvia Pfeiffer, Peter Tomczyk
* @version $Id: prgguide.htm,v 1.2 1998/01/27 14:43:31 tomczyk Exp tomczyk $
*/
class AudioData {

/**
   * laedt eine gegebene Anzahl von Samples aus der Audiodatei
   * in den Audiocache. Liefert die Anzahl der geladenen Werte
   * zurueck. Wird EOF erreicht, so gibt load eine kleinere
   * Zahl als die angegebene zurueck.
   *
   * @param samples Anzahl der Samples
   *
   * @return die Anzahl der geladenen Samples
   *
   * @exception IOException wenn ein Fehler beim lesen aufgetreten
   *            ist
   * @exception LogicException wenn samples kleiner 0 ist
   *
   * @see loadSecs
   */
virtual int load(int samples) const;

/// die Audiodatei
ifstream audiofile;

};

...und in der Programmdatei könnte dann etwas über das Format der Audiodaten stehen. Den Benutzer interessiert das nicht, denn das Format ist für ihn transparent!

Globale Typedefs, Konstanten etc.

Es dürfen keine globalen Typedefs, Enummeratoren, Konstanten oder Variablen definiert werden. In C ist es oft notwendig, in C++ nicht. Das vermeidet Namenskonflikte und macht die Teile der Bibliothek voneinander unabhängig. Hier ein paar Beispiele:

Statt des globalen Enumeratortypen:

enum { ROT, GELB, GRUEN } Farbe;

class Ampel {

public:
Farbe zustand() const;

private:
Farbe _zustand;
};

Farbe Ampel::zustand() const { return _zustand; }

sollte an dieser Stelle ein eingebetteter Enumeratortyp verwendet werden:

class Ampel {

public:
enum { ROT, GELB, GRUEN } Farbe;

Farbe zustand() const;

private:
Farbe _zustand;
};

Ampel::Farbe Ampel::zustand() const { return _zustand; }

Man braucht auch keine globalen Konstanten wie etwa:

const int MAX_LAENGE = 1000;

class Warteschlange {
};

wenn es static Elemente gibt:

class Warteschlange {

public:
static const int MAX_LAENGE;
};

const int Warteschlange::MAX_LAENGE = 1000;

Klar, am schnellsten sind die Makros, aber hier geht es nicht um die Geschwindigkeit!

Ausnahmen und Ausnahmebehandlung

In Fehlerfällen sollten die Objekte/Funktionen Ausnahmen erzeugen. Konstrukte wie dieser:

if (b == 0) {

cerr << "Division durch 0" << endl;

exit(1);

}

c = a / b;

dürfen nicht benutzt werden. In C++ gibt es für solche Fälle die Ausnahmen (exceptions):

if (b == 0)

throw Exception("Division durch 0");

c = a / b;

Statt das Programm abzubrechen, wird die Ausnahme bis zu der public-Schnittstelle "hochgereicht". So kann der Benutzer eines Objektes - der Aufrufer einer Funktion - selbst entscheiden, wie er reagiert. Die Klasse Exception ist bereits definiert. Bei der Übersetzung mit g++ muß -fhandle-exceptions angegeben werden.

Bitte, Ausnahmen in den Kommentaren vermerken. In docpp ist dafür das Feld @exception <Name der Exception-Klasse> <Erklärung, wann es zu der Ausnahme kommt> vorgesehen.

Ausgabeoperator <<

Für jede Klasse, die irgendwelche Zustandsinformationen, Zwischenergebnisse etc. speichert, sollte der Ausgabeoperator << definiert werden. So können Ergebnisse jederzeit angezeigt bzw. in einer Datei abgespeichert werden. Zur Erinnerung; der Ausgabeoperator wird wie folgt definiert:

ostream& operator<<(ostream& os, const X& x) {

// Anweisungen der Form os << x.daten;

return os;

}

Falls private deklarierte Elemente ausgegeben werden, muß der Ausgabeoperator eine friend-Funktion der Klasse X sein, d.h.:

class X {

friend ostream& operator<<(ostream& os, const X& x);

};

Last modified: $Id: prgguide.htm,v 1.2 1998/01/27 14:43:31 tomczyk Exp tomczyk $