Kommentare

Ed42 bietet eine umfangreiche Unterstützung bei der Erstellung und Pflege von Kommentaren. Dabei werden generell zwei Formen von Kommentaren unterschieden:
  • Zeilenübergreifende Kommentare, die ggf. aus mehreren Zeilen bestehen und ggf. strukturiert sind. Zeilen, die Teile eines zeilenübergreifenden Kommentars enthalten, enthalten keinen Code, der nicht zum Kommentar gehört.
  • Kurzkommentare, die vom Kommentarbeginn nur bis bis zum Zeilenende reichen. Vor einem Kurzkommentar kann in der gleichen  Zeile ein anderer Text stehen.


Beispiel: Das folgende Codefragment enthält einen zeilenübergreifenden Kommentar und zwei Kurzkommentare.

/*-------------------------------------------------------------------------*/
/* Falls kein Datum angegeben wird (du == 0) werden als Default Striche    */
/* eingesetzt ...                                                          */
/*-------------------------------------------------------------------------*/
strcpy(s, "--------------");

if (du == 0)
   return (s);

cvdatetime(&dttm, du);

switch (datum_darstellung)
{
   case DARST_NN_NN_NN:                  // DD.MM.YY
      sprintf(s, "%02d.%02d.%02d",
                 dttm.dttm_mday,
                 dttm.dttm_month,
                 dttm.dttm_year % 100);
      break;

   case DARST_NN_MON_NN:                 // DD.MON YY
      sprintf(s, "%02d.%s.%02d",
                 dttm.dttm_mday,
                 monat_kurz_bez[dttm.dttm_month-1],
                 dttm.dttm_year % 100);
      break;

   default:
       break;
}


Strukturierung von zeilenübergreifenden Kommentaren

Ed42 bietet zwei alternative Methoden zur Strukturierung von zeilenübergreifenden Kommentaren:
  1. Strukturierung über Kommentar-Tags. Diese Form der Strukturierung von Kommentaren wird beispielsweise durch das Tool javadoc unterstützt, das in der Lage ist, aus entsprechenden Kommentaren in Java-Files eine Dokumentation des Quellcodes zu erstellen.
  2. Strukturierung über die Formatierung des Kommentars.
Über die Projektoptionen  (Registerkarte Sprache/Kommentare) kann der Benutzer wählen, welche Form der Strukturierung verwendet werden soll (um die erste Form zu wählen, muß die Auswahlbox Java-Style Kommentare verwenden aktiviert werden).

Auch die Behandlung von Kurzkommentaren hängt davon ab, für welche Form der Kommentarstrukturierung man sich entschieden hat. Im folgenden wird die Behandlung von Kommentaren bei Wahl der zweiten Alternative beschrieben. Die Dokumentation zur Verwendung von Java-Style-Kommentaren ist in einem separaten Abschnitt abgelegt.

Neben der Unterscheidung zwischen Kurz- und zeilenübergreifenden Kommentaren wird zusätzlich zwischen einfachen (bzw. unstrukturierten) und strukturierten Kommentaren unterschieden: Ein einfacher Kommentar ist entweder ein Kurzkommentar oder ein zeilenübergreifender Kommentar, dessen Kommentartext nicht strukturiert ist (d.h. der Kommentartext besteht lediglich aus einem Textblock). Dagegen besteht ein strukturierter Kommentar aus (ggf. mehreren ) Abschnitten, die bestimmten Formatierungsregeln genügen müssen. Damit der Benutzer sich nicht mit diesen Formatierungsregeln 'herumschlagen' muß, können strukturierte Kommentare über einen entsprechenden Dialog erzeugt werden. Ed42 unterstützt die Behandlung von strukturierten Kommentaren für die folgenden Konstrukte:

  • Modulheader,
  • Funktionen,
  • Prozeduren,
  • Klassen-
  • Interface- und
  • Strukturdefinitionen
Im Rahmen der Sprachunterstützung kann die Menge der unterstützten Konstrukte sowie die Form der Unterstützung eingeschränkt werden (so macht es z.B. keinen Sinn in einem C-Programm die Erzeugung von Klassen-Kommentaren anzubieten).

Die folgenden Unterabschnitte beschreiben die Erstellung, Modifikation und Formatierung von einfachen und strukturierten Kommentaren:


Einfache Kommentare erzeugen: Einfache Kommentare können über Kommentare|Kommentar erzeugen oder über das PopUp-Menü, das über das Drücken der rechten Maustaste erreicht werden kann, erstellt werden. Es wird ein Dialog angezeigt, in dem angegeben werden muß, ob ein Kurz- oder Langkommentar erzeugt werden soll. Soll ein Langkommentar erzeugt werden, kann weiterhin angegeben werden, ob der Kommentar mit einer zusätzlichen Start- und Endezeile versehen werden soll. Des weiteren ist der Fließtext für den Kommentar einzugeben. Ein Langkommentar wird immer vor der aktuellen Zeile eingefügt, ein Kurzkommentar wird (falls möglich) in der aktuellen Zeile eingefügt. Zur Formatierung eines Kommentars werden die Projekteinstellungen (Registerkarte Sprache/Kommentare) berücksichtigt. Dort kann konfiguriert werden, in welcher Spalte Kurzkommentare beginnen sollen und in welcher Spalte Kommentare enden sollen.

Einfache Kommentare modifizieren: Befindet sich der Cursor auf einem einfachen Kommentar, kann über Kommentare|Kommentar modifizieren bzw. den entsprechendenMenüpunkt des PopUp-Menüs, das über die rechte Maustaste erreichbar ist, die Änderung des Kommentars angestoßen werden. Es erscheint ein Dialog, in dem der Fließtext des Kommentars editiert werden kann.

Einfache Kommentare formatieren: Wird ein einfacher Kommentar direkt im Quelltext verändert, kann er über Kommentare|Kommentar formatieren bzw. den entsprechendenMenüpunkt des PopUp-Menüs, das über die rechte Maustaste erreichbar ist, formatiert werden. Für die Formatierung gelten die unter Einfache Kommentare erzeugen beschriebenen Regeln.
 

Strukturierte Kommentare erstellen: Die Erstellung eines strukturierten Kommentars wird über Kommentare|Kommentar erzeugen bzw. den entsprechenden Eintrag im PopUp-Menü, das über die rechte Maustaste erreichbar ist, eingeleitet. Es wird ein Dialog angezeigt, in dem der Bediener zunächst angeben muß, für welches Konstrukt (Modul, Funktion, Prozedur, Klasse, Interface, Struktur) ein Kommentar erstellt werden soll. Des weiteren muß ein Namen für das Konstrukt eingeben werden. Ist im aktuellen Text ein Wort markiert, wird dieses Wort als Vorgabe angezeigt. Ist festgelegt, für welches Konstrukt ein Kommentar erstellt werden soll, werden in Abhängigkeit von dieser Vorlage weitere Dialogseiten (erreichbar über Registerkarten) zur Eingabe von Informationen angeboten. Die folgende Tabelle gibt an, welche Informationen für welches Konstrukt vom Bediener angegeben werden können.
 
Konstrukt Informationen, die angegeben werden können
Modul Name des Moduls, Aufgabe des Moduls, Abhängigkeiten des Moduls (z.B. von anderen Modulen), Autor , Erstellungsdatum, Änderungen (mit dem jeweiligen Datum der Änderung, Autor und Beschreibung der Änderung), offene Punkte. Für Autor- und Firmenangaben werden die über Hilfe|Info eingegebenen Benutzerinformationen als Standardvorgaben verwendet.
Klasse Name, Attribute (mit Name, Typ, Modus und Erläuterung), Methoden (mit Name und Erläuterung), Aufgabe, Implementierungshinweise, Autor, Erstellungsdatum, Änderungen (mit dem jeweiligen Datum der Änderung, Autor und Beschreibung der Änderung). Für Autor- und Firmenangaben werden die über Hilfe|Info eingegebenen Benutzerinformationen als Standardvorgaben verwendet.
Interface Name, Attribute (mit Name, Typ, Modus und Erläuterung), Methoden (mit Name und Erläuterung), Aufgabe.
Struktur Name, Elemente (mit Name, Typ, und Erläuterung), Aufgabe.
Prozedur Name, Name der Klasse (nur bei Methoden), Parameter (mit Namen, Typ, Modus und Erläuterung), erzeugte Exceptions, Aufgabe und Implementierungshinweise.
Funktion Name, Name der Klasse (nur bei Methoden), Parameter (mit Namen, Typ, Modus und Erläuterung), Rückgabewert (mit Typ und Erläuterung), erzeugte Exceptions, Aufgabe und Implementierungshinweise.

Der automatisch von Ed42 erstellte Kommentar spiegelt die Informationen wieder, die eingegeben wurden. Der Kommentar wird oberhalb der aktuellen Zeile in das aktuelle Dokument eingefügt. Zur Formatierung des Kommentars werden die Projekteinstellungen berücksichtigt (s.o.).

Beispiel: Das folgende Codefragment enthält einen für eine Funktion automatisch formatierten Kommentar.

/*****************************************************************************/
/*-Funktion: PV_SetzeAbgang                                                  */
/*---------------------------------------------------------------------------*/
/*-Aufgabe:                                                                  */
/* Festlegen des Abgangsortes. Die nachfolgenden Tarifierungen verwenden den */
/* eingestellten Abgangsort als Startpunkt bei der Suche von Relationen.     */
/*---------------------------------------------------------------------------*/
/*-Parameter:                                                                */
/* Input betreiber_id : uint                                                 */
/*    Id des Betreibers (in der Regel die Id des Verbundes)                  */
/* Input ta_tarif_typ_id : ulong                                             */
/*    Kodiert, welche Angebote und Verkehre verkauft werden duerfen          */
/* Input sprach_id : uint                                                    */
/*    Id der verwendeten Sprache (deutsch = 400)                             */
/* Input waehrung_id : uint                                                  */
/*    Id der verwendeten Waehrung (DM = 276)                                 */
/* Input bezeichner : char *                                                 */
/*    Bezeichner der Ausgabestelle                                           */
/* Input abgangsort_position : ulong                                         */
/*    Position der Ausgabestelle                                             */
/*---------------------------------------------------------------------------*/
/*-Funktionsergebnis:                                                        */
/*-Typ: bool                                                                 */
/*    TRUE = Setzen des Abgangsortes war erfolgreich, FALSE sonst            */
/*---------------------------------------------------------------------------*/
/*-Implementierungshinweise:                                                 */
/*****************************************************************************/
bool PV_SetzeAbgang(uint   betreiber_id,
                    ulong  ta_tarif_typ_id,
                    uint   sprach_id,
                    uint   waehrung_id,
                    char  *bezeichner,
                    ulong  abgangsort_position);

Strukturierte Kommentare ändern: Die Änderung wird analog zur Änderung von einfachen Kommentaren angestoßen (Kommentare|Kommentar modifizieren bzw. über PopUp-Menü). Dem Bediener wird ein Dialog angeboten, der die gleichen Eingabemöglichkeiten wie bei der Erstellung eines strukturierten Kommentars (nach der Wahl des Konstrukts) enthält. Die Informationen des bestehenden Kommentars werden in den Dialogfeldern zur Änderung dargestellt, d.h. Ed42 ist in der Lage, den vorhandenen strukturierten Kommentar zu parsen. Daraus ergibt sich die Notwendigkeit, daß mit Hilfe von Ed42 erzeugte Kommentare nicht verändert werden; ansonsten können Informationen bei der Änderung eines Kommentars verloren gehen (es können im Quelltext durchaus Änderungen an Kommentaren vorgenommen werden; wichtig ist, daß die Struktur der Kommentare nicht verändert wird. Z.B. stellt das Verrutschen der schließenden Kommentarzeichen durch Textänderungen kein Problem dar).

Strukturierte Kommentare formatieren: Wir ein Strukturierter Kommentar im Quelltext geändert, kann er analog zu einem einfachen Kommentar über über Kommentare|Kommentar formatieren bzw. den entsprechenden Menüpunkt des PopUp-Menüs, das über die rechte Maustaste erreichbar ist, formatiert werden. Für die Formatierung gelten die unter Strukturierte Kommentare erstellen gemachten Aussagen. Zur Modifikation von strukturierten Kommentaren vgl. aber Strukturierte Kommentare ändern.

Ersetzen von Umlauten: Sowohl für einfache als auch für strukturierte Kommentare bietet Ed42 die Möglichkeit an, alle Umlaute in Kommentaren zu ersetzen, bevor sie in den Quellcode eingearbeitet werden. Das Feature kann über die Projektoptionen (Registerkarte Sprache/Kommentare) aktiviert werden.


Last Change: 27.10.2001
© Copyright by Stefan Brüning. All rights reserved