Kommentare

Allgemeines

1. Ein überflüssiger Kommentar kostet Platz – ein fehlender Kommentar kostet Geld!
2. Kommentare sind grundsätzlich in deutsch gehalten.
3. Die Themenüberschriften in Datei-, Klassen- und Funktionsköpfen (‘CREATED’, ‘DECLARATION’ u.s.w.) haben die Bedeutung von Schlüsselwörtern (auch wenn der Compiler dies nicht unterstützt) und werden deshalb nicht deutsch verwendet.
4. (C++, Delphi) Erstreckt sich ein Kommentar über mehrere Zeilen, so beginnen alle Zeilen mit //.

// Das ist ein mehrzeiliger Kommentar,
// der die Formatierung von Folgezeilen
// in C++ und Delphi veranschaulicht.

5. (C, Pascal) Erstreckt sich ein Kommentar über mehrere Zeilen, so beginnen die Folgezeilen mit „//". Da das Kommentarende-Symbol „*/" den Charakter einer schließenden Klammer hat, steht es auf derselben Einrückungsebene, wie das einleitende „/*".

C	Pascal
/* Das ist ein mehrzeiliger Kommentar, // der die Formatierung von Folgezeilen // in C veranschaulicht. */	(* Das ist ein mehrzeiliger Kommentar, // der die Formatierung von Folgezeilen // in Pascal veranschaulicht. *)

Diese Vorschrift erleichtert es, vor allem C-Headerfiles mit einer einzigen Vorschrift in der PVCS-Versionsverwaltung zu aktualisieren. Unterstützt der C-Compiler bereits die C++ Kommentare „//", so sind diese unbedingt der eben beschriebenen Form vorzuziehen.

Quelltext

Den Sourcecode begleitende Kommentare sind dort (in einzelnen Zeilen aufzunehmen), wo schwer nachzuvollziehende Codeteile oder funktionale Untergliederungen innerhalb einer Funktion vorhanden sind.

Dateien

Alle Dateien erhalten folgenden Kommentarkopf (Beispieltext kursiv):

//-------------------------------------------------------------------
// PROJECT      Projektname/Subsystemname/…
// $Workfile$
// $Revision$
// PREFIX       Prefix für öffentliche Funktionen und Datenobjekte
// DESCRIPTION  Beschreibung des in dieser Datei implementierten
//              Moduls.
// CREATED      11-Dez-95, U.Sauerland - © ADVICE Softwarelösungen
// MODIFIED     20-Dez-95, U.Sauerland - © ADVICE Softwarelösungen
//                  Zusammenfassung der Änderungen, falls diese
//                  viele Stellen in der Datei betreffen.
//-------------------------------------------------------------------
// $Log$
//-------------------------------------------------------------------
// TABSIZE      4
// CHARSET      WINDOWS
//-------------------------------------------------------------------

Klassen

Klassendeklarationen werden mit folgendem Kopf eingeleitet:

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

class CKonfiguration : public CBasis

// PATTERN      Entwurfsmusterindex und -name
// PREFIX       Typenprefix-Kürzel z.B. knf
// DESCRIPTION  Beschreibung der Klasse und ihrer Aufgaben
// CREATED      11-Dez-95, U.Sauerland - © ADVICE Softwarelösungen
// MODIFIED     20-Dez-95, U.Sauerland - © ADVICE Softwarelösungen
//                  Beschreibung der Änderung
{
    // Deklarationen
}

Datenobjekte

Konstanten, globale Variablen und Typen erhalten einen kurzen Kommentar in derselben Zeile oder eingerückt in der folgenden Zeile zur Erklärung des Verwendungszwecks.

#define MAX_ALARME  42  // Anzahl der maximal möglichen Alarme

typdef struct           // Modellierung komplexer Zahlen
{
    float m_fReal;      // Realteil der Zahl
    float m_fImag;      // Imaginärteil der Zahl
} CComplex;

class CKlimasteuerung
{
    …
    private:
        float m_fMinimaleLuftfeuchtigkeit;
            // relative Luftfeuchtigkeit (in %), die
            // auf gar keinen Fall unterschritten
            // werden darf.
    …
}

Funktionen

Funktionsdeklarationen

Funktionsdeklarationen werden wie folgt kommentiert und formatiert:

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

class CKlasse

// Klassenbeschreibung

{
    …
    public: int Funktion
        (
            const int nParam1     // Eingabeparameter
            const int* pParam2    // Ausgabeparameter
        )
        const                     // falls erforderlich (C++)
        throw (CException, …);    // falls erforderlich (C++)
        // DECLARATION      (polymorphic|override)    // optional
        //                    polymorphic: Die Funktion kann
        //                                 polymorph überladen werden.
        //                    override   : Die Funktion überlädt eine
        //                                 polymorphe Funktion einer
        //                                 Basisklasse.
        // OPERATION TYPE   (constructor|destructor|modifier|selector)
        //                    constructor: Konstruktor
        //                    destructor : Destruktor
        //                    modifier   : Funktion ändert Element-
        //                                 variablen bzw. ändert den
        //                                 Zustandsvektor (z.B. durch
        //                                 Änderung von Elementvaria-
        //                                 blen zu denen eine Referenz-
        //                                 beziehung besteht)
        //                    selector   : die Funktion ändert
        //                                 Elementvariablen bzw. den
        //                                 Zustandsvektor nicht.
        //                    agent      : Die Funktion führt Operatio-
        //                                 nen für Exemplare einer an-
        //                                 deren Klasse aus oder die
        //                                 Funktion ist nicht Element
        //                                 einer Klasse, führt aber
        //                                 Operationen für Objekte aus.
        // PUBLICS USED       READ       : nur lesend verwendete
        //                                 öffentliche Datenobjekte
        //                    READWRITE  : lesend und schreibend
        //                                 verwendete öffentliche
        //                                 Datenobjekte
        //                    WRITE      : nur schreibend verwendete
        //                                 öffentliche Datenobjekte
        // PRECONDITIONS      Zusicherungen, die vor Aufruf der Funktion
        //                    erfüllt sein müssen.
        // DESCRIPTION        Beschreibung der Aufgabe(n) und ggf. des
        //                    Algorithmus der Funktion.
        // POSTCONDITIONS     Zusicherungen, die nach Aufruf der Funktion
        //                    erfüllt sind.
        // RETURN VALUE       Beschreibung der Rückgabewerte
        //                    (darf bei void-Funktionen entfallen).
};

Beispiel:

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

class CIntListe

// Klassenbeschreibung

{
    …
    public: int CIntListe::Maximium
        (void)
        const
        throw (xmsg);
        // OPERATION TYPE   selector
        // PRECONDITIONS    Die Liste darf nicht leer sein.
        // DESCRIPTION      Verwendet einen Iterator aus der classlib,
        //                  um die unsortierte Liste zu durchsuchen.
        // POSTCONDITIONS   Die Länge der Liste wird durch die
        //                  Funktion nicht geändert.
        // RETURN VALUE     Der größte Wert in der Liste
    …
};

Funktionsdefinitionen

Im Kopf einer Funktionsdefinition wird aufgeführt, wer wann welche Änderungen vorgenommen hat

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

int CKlasse::Funktion
    (void)
    // CREATED  18-Dez-95, U.Sauerland - © ADVICE Softwarelösungen
    // MODIFIED 12-Dez-96, U.Sauerland - © ADVICE Softwarelösungen
    //              Beschreibung der Veränderung

Beispiel:

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

int CIntListe::Maximium
    (void)
    const
    throw (xmsg)
    // CREATED  18-Dez-95, U.Sauerland - © ADVICE Softwarelösungen
    // MODIFIED 20-Dez-95, U.Sauerland - © ADVICE Softwarelösungen
    //              Vorzeichenfehler bei Vergleich beseitigt
    //          17-Apr-96, U.Sauerland - © ADVICE Softwarelösungen
    //              Workaround wegen BORLAND-Iterator-Bug
{
    REQUIRE(0 != Laenge());
        // Die Liste ist nicht leer.
    OLD(CIntListe);

    int nResult = -MAXINT;

    // Anweisungen

    ENSURE(old.Laenge() == Laenge());
        // Die Funktion hat die Länge der Liste nicht geändert.
}

[zurück] | [weiter] | [Inhalt] | [Einleitung] | [Layout] | [Programmierstil] | [Anhänge]

Copyright © 1996-98 by Uwe Sauerland