Kommentare

  • Allgemeines
  • Quelltext
  • Dateien
  • Klassen
  • Datenobjekte
  • Funktionen
  • Funktionsdeklarationen
  • Funktionsdefinitionen

  • 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 //.
      1. // 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 „/*".
      1. 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.

    Funktionen

    Funktionsdeklarationen

    Funktionsdeklarationen werden wie folgt kommentiert und formatiert:

    Beispiel:

    Funktionsdefinitionen

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

    Beispiel:


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


    Copyright © 1996-98 by Uwe Sauerland