Programmierkurs C-Sharp: Kommentare und Dokumentation

Aus Wikibooks

Wechseln zu: Navigation, Suche

Regal: Programmierung

Programmierkurs C#

Kommentare und Dokumentation

Inhaltsverzeichnis

1 Problem
2 Kommentare und Dokumentation
3 Weblinks

[Bearbeiten] Problem

Um es gleich vorweg zu nehmen: Dieses Kapitel ist das Wichtigste, das wir überhaupt in diesem Buch lesen können.

"Kommentare? Ausgerechnet Kommentare?
Aber damit schreibt man doch keine Programme! Programmcode muss her!
Je mehr, desto besser! Und je kryptischer, desto schöner!"

Wirklich? Fein. Was hältst du denn von folgender Zeile reinen Programmcodes?

bool istErlaubt = (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")));

Toll, oder? Aber abgesehen von "toll", 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 istErlaubt = (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 eine einfache Faustregel sagt

	Jeder Programmierer ist nur so gut wie seine Kommentare. Man muss allein anhand der Kommentare erkennen können, was das Programm macht.

Als gute Programmierer sparen wir also gern und oft an Quellcode. An Kommentaren sollten wir aber nie geizen.

[Bearbeiten] Kommentare und Dokumentation

In C# sind sowohl Zeilen- als auch Blockkommentare möglich, ferner gibt es noch spezielle XMLDoc-Kommentare, aus denen eine Dokumentation im XML-Format generiert werden kann.

[Bearbeiten] Zeilenkommentare

Zeilenkommentare beginnen mit zwei aufeinanderfolgenden Schrägstrichen // und enden in der gleichen Zeile mit dem Zeilenumbruch. Alles was nach den Schrägstrichen folgt, wird bis zum Zeilenende als Kommentar angesehen, einschließlich 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>

[Bearbeiten] Blockkommentare

Blockkommentare, die sich über mehrere Zeilen erstrecken können, beginnen mit der Buchstabenkombination /* und enden mit */. Kommentare können sowohl am Zeilenanfang als auch mitten in einer Zeile beginnen. Blockkommentare können in der selben Zeile enden, und es kann ihnen Quelltext folgen, der vom Compiler ausgewertet wird. Alles was innerhalb des Blockkommentars steht, wird vom Compiler übergangen.

Blockkommentare können nicht geschachtelt werden, da auch das /* übergangen wird, und 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> */

[Bearbeiten] XML-Kommentare

Zur Dokumentation stellt C# in Form von "Metadaten" (Attribute) einen Mechanismus bereit, der es ermöglicht, eine XML-basierte Dokumentation erzeugen zu lassen.

Zur Dokumentation von Typen steht eine spezielle Form von Zeilenkommentaren bereit. Hierzu beginnt der Zeilenkommentar mit einem weiteren, dritten Schrägstrich (///) und befindet sich direkt über dem zu dokumentierenden Typ. Es folgen nun XML-Tags, die jeweils eine bestimmte Funktion bei der Dokumentation übernehmen, beispielsweise eine Zusammenfassung über ein "Summary"-Tag.

/// <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 auf eine externe Ressource referenziert werden, die die Dokumentation enthält.

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

Dokumentation im XMLDoc-API-Dokumentationsformat wird vom Compiler als ein 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 extrahiert.