Arbeiten mit .NET: C-Sharp/ Grundlagen/ Bestandteile/ Kommentare

Dieses Kapitel führt zu einem der wichtigsten Hilfsmittel für Programmierer.

Problem

Setzen wir einmal das Fazit an den Anfang:

	Merke Ein Programm ohne Kommentar ist ähnlich viel wert wie ein Kommentar ohne Programm – nichts!

Vielleicht schreien Sie jetzt auf: Aber mit Kommentaren schreibt man doch keine Programme! Programmcode muss her – je mehr, desto besser!

Wirklich? Dann vergleichen Sie einmal folgenden „reinen“ Programmcode:

bool isValid = (System.Threading.Thread.CurrentPrincipal.IsInRole("Manager"))   ?
                SetRole(Retrieve(GetRights(isRegistered||isMarked)),true,false) :
                WriteToDataBase(GetLog(LoadDataTable(CalculateTime(DateTime.Now,true) ,
                "DbLocal"), System.Threading.Thread.CurrentPrincipal.IsInRole("SystemUser")));

Sieht doch „toll“ aus, nicht wahr? Aber was genau macht diese Zeile hochoptimierten Programmcodes? Und wenn wir das schon herausbekommen, wie lange brauchen wir dafür? Wie wäre es stattdessen mit diesem Code?

// Wir prüfen, ob der Benutzer in der Rolle "Manager" ist.
 // Wenn ja, setzen wir die Rollenrechte 
 //          + "Monatsbericht lesen erlaubt" und 
 //          + "Monatsbericht drucken geerbt".
 //
 // Wenn nein, schreiben wir einen Logeintrag
 //            in die Überwachungsdatenbank.
 //            Dabei halten wir gleichzeitig
 //            + den Benutzer,
 //            + den Ort des aktuellen Zugriffsversuchs,
 //            + das Datum,
 //            + und die Zeit fest.
 //
 bool isValid = (System.Threading.Thread.CurrentPrincipal.IsInRole("Manager"))   ?
                 SetRole(Retrieve(GetRights(isRegistered||isMarked)),true,false) :
                 WriteToDataBase(GetLog(LoadDataTable(CalculateTime(DateTime.Now,true) ,
                 "DbLocal"), System.Threading.Thread.CurrentPrincipal.IsInRole("SystemUser")));

Der Programmcode wurde nicht verändert. Aber er ist viel einfacher lesbar, nicht wahr?

Kommentare müssen keineswegs ganze Bücher füllen, aber es gibt zwei Faustregeln:

• Alle Bezeichner – Klassen mit ihren Eigenschaften, Methoden und Ereignissen sowie die Variablen – müssen „sprechende“ Namen erhalten, damit ihre Bedeutung jederzeit und für jedermann klar ersichtlich ist.
• Für das, was das Programm und seine Bestandteile enthalten, ist so wenig Kommentar wie möglich, aber immer so viel Kommentar wie nötig einzufügen.

Der obige Code-Schnipsel muss also unbedingt erklärt werden. Überflüssig und nur hinderlich ist dagegen der folgende Kommentar. Denn der Name der Methode Math.Abs sagt klar, was gemacht werden soll; auch ist sofort zu erkennen, dass die Variable diff verwendet wird:

// hole den Absolutbetrag des Inhalts der Variablen diff
double result = Math.Abs(diff);

Kommentare und Dokumentation

In C# gibt es sowohl Zeilen- als auch Blockkommentare. Ferner gibt es spezielle XMLDoc-Kommentare, aus denen eine Dokumentation im XML-Format generiert werden kann.

Zeilenkommentare

Zeilenkommentare beginnen mit zwei aufeinanderfolgenden Schrägstrichen // und enden am Ende der gleichen Zeile mit dem Zeilenumbruch. Alles, was nach den Schrägstrichen folgt, wird bis zum Zeilenende als Kommentar angesehen, einschließlich weiterer Block- und XMLDoc-Kommentare.

// Ein Zeilenkommentar endet mit dem Ende der Zeile
 int a = 3; // Zeilenkommentar am Ende der Zeile
 
 // /* Compilerfehler:
 public class OhneKlammer {
 */
 
 // /// <summary>Das hier erscheint nicht im XMLDoc!</summary>

Blockkommentare

Blockkommentare beginnen mit der Zeichenkombination /* und enden mit der Kombination */. Solche Kommentare können sowohl am Zeilenanfang als auch mitten in einer Zeile beginnen und enden; sie erstrecken sich üblicherweise über mehrere Zeilen. Alles, was innerhalb des Blockkommentars steht, wird vom Compiler übergangen; was nach einem Blockende in derselben Zeile noch folgt, wird vom Compiler ausgewertet.

Blockkommentare können nicht geschachtelt werden, da auch das /* übergangen wird; ebenso kommentieren Blockkommentare auch XMLDoc-Kommentare aus.

/* Ein einfacher Blockkommentar
    zur Demonstration mehrzeiliger
    Kommentare */
 
 // Auskommentierter Code
 /*
    int a=0;
 */
    float a=0.0;
 
 // schlechter Stil
 /*void*/ int EineFunktion() {
   System.Console.WriteLine(/*"Zugabe!Zugabe!"*/ "Buuuhhuuu!"); 
   return 1;
 }

 // Compilerfehler: Keine geschachtelten Kommentare
 /* Start 1
 /* Start 2
    Ende 2 */
    Ende 1 ?? */

 // Generiert kein XML-Doc (erwartungsgemäß)
 /* /// <summary>Gibt es nicht mehr</summary> */

XML-Kommentare

Mit einer speziellen Form von Zeilenkommentaren steht ein Mechanismus bereit, mit dem eine XML-basierte Dokumentation des Programms erzeugt werden kann. Hierzu beginnt der Zeilenkommentar mit einem weiteren, dritten Schrägstrich /// direkt über einem Element, das dokumentiert werden soll. In diesen Kommentarzeilen folgen XML-Tags, die jeweils eine bestimmte Funktion bei der Dokumentation übernehmen.

Das folgende Beispiel beschreibt eine Methode mul und benutzt die folgenden Tags:

• <summary> für die Zusammenfassung
• <returns> zur Erläuterung des Rückgabewerts
• <param> zur Erläuterung der Parameter

/// <summary>Diese Funktion multipliziert zwei int.</summary>
 /// <returns>Das Produkt der Parameter</returns>
 /// <param name="a">Erster Faktor</param>
 /// <param name="b">Zweiter Faktor</param>
 public int mul(int a, int b) { return a*b; }

Alternativ kann auch eine externe Ressource referenziert werden, die die Dokumentation enthält.

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />

Normalerweise wird diese Art der Dokumentation vom Compiler als normaler Zeilenkommentar angesehen. Erst durch Angabe der Compiler-Option „/doc:Dateiname“ werden Kommentare, die mit drei Schrägstrichen beginnen, als XMLDoc erkannt und aus dem Quellcode übernommen. Zusätzlich werden diese Erläuterungen im Code-Editor ausgewertet und angezeigt, sobald der Anwender mehr Informationen über eine Methode sehen möchte.

Siehe auch

Genauere Erläuterungen zum XML-Kommentaren mit einer Aufstellung der Markierungen gibt es im Kapitel Dokumentation erstellen des Framework-Buchs.

Microsoft stellt die „offiziellen“ Erläuterungen bereit:

• Recommended Tags for Documentation Comments (englisch)
• Empfohlene Tags für Dokumentationskommentare C# (deutsch)

Hilfreich sind Programme zum Erstellen einer Dokumentation, beispielsweise:

• NDoc