[C#] 3 Arten des richtigen Kommentieren

[C#] 3 Arten des richtigen Kommentieren

Guten Tag,

ich werde euch drei Arten der Kommentierung näherbringen, da die Kommentierung bei größeren Programmcode/Projekten essenziell wird.
Ein schönes Beispiel ist zum Beispiel. Zwei Programmierer arbeiten an einem gemeinsamen Projekt. Programmierer B macht nachts größere Änderungen und schläft dementsprechend tagsüber. Programmierer A möchte nun weiterarbeiten und weiß nichts von den Änderungen. Nun muss er sich den kompletten Quellcode durchlesen und versuchen es verstehen, da keine Kommentierung vorhanden ist.

Fangen wir nun an. Folgende Arten werden wir durchgehen
  • Einzeiler Kommentare
  • Mehrzeiler Kommentare
  • XML Kommentare

Einzeiler Kommentare
Diese Art des kommentieren wird meist für kurze Hinweise oder ToDos verwendet und sieht wie folgt aus. Dafür habe ich euch ein kleines Beispiel geschrieben, welches wir später weiternutzen werden.
C#:
    class Program
    {
        static void Main(string[] args)
        {
            // ToDo hier muss noch was getan werden
        }
    }

Mehrzeiliger Kommentare
Wechseln wir nun zum Gegenstück der einzeiligen Kommentierung. Wer hätte es erwartet? Die mehrzeilige Kommentierung!

Bei der mehrzeiligen Kommentierung werden meist umfangreichere Eigenschaften o.ä beschrieben außerdem verwenden viele dies auch zum kurzfristigen Deaktivieren von Programmcode.

Der Kommentar beginnt mit /* und hört mit */ auf. In diesem Beriech darf nicht geschachtelt werden!

C#:
    class Program
    {
        static void Main(string[] args)
        {
            /*
             * Deklaration des Objektes Taschenrechner
             */
            Taschenrechner tRechner = new Taschenrechner();
        }
    }

    class Taschenrechner { }

XML Kommentare
Die wichtigste Art des Kommentieren, seitdem es IntelliSense gibt. Mit dieser Art werden Kommentare durch bestimmte tags funktionell gestaltet. Jetzt wirst du dich bestimmt fragen. Was sind tags und welche gibt es? Eine Liste mit den meistverwendeten findet Ihr nach dem Beispiel.

Ein "tag" ist vergleichbar mit einer Return-Methode. Im Inneren wird etwas verarbeitet und etwas wird return. Ein Tag-Beispiel wäre beispielsweise.
XML:
<summary>Das ist eine Zusammenfassung!</summary>

Was bringt uns das? Kurz gesagt Ihr erstellt eine Funktion, z.B. s.u, so erhaltet Ihr beim deklarieren der Funktion mittels IntelliSense (Autovervollständigung gehört dazu) die Zusammenfassung.

Wenn wir das Ganze auf ein C# Beispiel beziehen könnte es wie folgt aussehen.

xml-kommentar.png


Ein anderes Beispiel wäre, das wir ein Beispiel (example) angeben können mittels des <example> Tag. Dieser Tag ist erweiterbar mit einem Code-Beispiel.

Der Aufbau würde so aussehen.
Code:
    /// <summary>
    /// Das ist die Zusammenfassung der Klasse Taschenrechner
    /// </summary>
    /// <example>
    /// Die Deklarierung der Klasse sollte so aussehen
    /// <code>
    /// class TestClass
    /// {
    ///     static int Main()
    ///     {
    ///        Taschenrechner tBezeichner = new Taschenrechner();
    ///     }
    /// }
    /// </code>
    /// </example>
    class Taschenrechner { }

Ein weiterer wichtiger Apspekt sind die Bemerkungen die wir mit dem Tag <remarks> setzen. Dieser wir in folgendem Beispiel mit dem Tag <see> und dem Attribut "cref" versehen, damit gewerkstelligen wir eine Beschreibungen mit einem Zeiger auf die Generic<T> Klasse.
Code:
   /// <summary>
    /// GenericClass.
    /// </summary>
    /// <remarks>
    /// This example shows how to specify the <see cref="GenericClass{T}"/> type as a cref attribute.
    /// </remarks>
    class GenericClass<T>
    {
        // Fields and members.
    }
Dieses Beispiel findet Ihr u.a. unter weiteren Hilfen.

Eine vollständige Liste der Tags/Attribute findet Ihr unter https://msdn.microsoft.com/de-de/library/5ast78ax.aspx

Ich hoffe ich konnt euch das Kommentieren etwas näherbringen. Ich behalte mir außerdem das Recht vor, dieses Tutorial weiterführend zu erweitern zu bearbeiten.
Autor
Halfbax
Aufrufe
5.945
First release
Last update
Bewertung
4,00 Stern(e) 1 Bewertungen

Latest updates

  1. Version 0.2 - Bearbeitung der XML Kommentierung

    Erweiterung der XML Kommentierung unter folgenden Aspektpunkten weitere Beispiele Attribute

Neueste Bewertungen

EIne gute Übersicht
Zurück