Dokumentation
Warum kommentieren?
...
Kommentare in C#
C# und Visual Studio bieten verschiedene Möglichkeiten an, Kommentare zu verfassen. Neben den einzeiligen Kommentaren, die nur für kurze Anmerkungen verwendet werden sollten, gibt es noch mehrzeilige Kommentare oder XML Kommentare, mit denen sich der Quellcode gut dokumentieren lässt.
Einzeilige Kommentare
Einzeilige Kommentare beginnen mit zwei Slashes und enden automatisch am Ende der Zeile:
//Dies ist ein einzeiliger Kommentar. Er endet automatisch am Ende der
//Zeile, so dass // in jeder Zeile wiederholt werden muss.
int i = 0; // Einzeilige Kommentare können auch in der Mitte einer Zeile beginnen
Abgegrenzte Kommentare
Ein Stern nach einem Slash (/*) leitet einen Kommentarblock ein. Der Kommentar endet erst, wenn das das entsprechende Token zum beenden des abgegrenzten Kommentars gefunden wurde (*/).
/* Dies ist ein mehrzeiliger
Kommentar. Ich brauche nicht
jede Zeile wieder neu als
Kommentar markieren. */
XML Kommentare
Mit XML Kommentaren können Klassen, Methoden, Eigenschaften, etc. zusätzliche Meta Informationen mitgegeben werden, um die Dokumentation des Codes zu erleichtern. Gibt man in Visual Studio vor einer bereits deklarierten Prozedur das dritte Slash (/) ein, so werden anhand der Signatur der Funktion automatisch die notwendigen XML Tags erstellt.
/// <summary>
/// Calculates length of the hypotenuse in a right-angled triangle.
/// (Pythagorean theorem)
/// </summary>
/// <param name="a">length of first leg</param>
/// <param name="b">length of second leg</param>
/// <returns>length of hypotenuse</returns>
public double GetHypotenuse(double a, double b)
{
return Math.Sqrt(Math.Pow(a, 2) + Math.Pow(b, 2));
}
Mit XML Kommentaren lässt sich zum Beispiel auch angeben, ob und wann Exceptions auftreten können oder es lassen sich Querverweise zu anderen Stellen im Code definieren. [1]
Praktisch an XML Kommentaren ist, dass diese automatisch in einem Tooltip erscheinen, wenn die entsprechend dokumentierte Klasse, Funktion, etc. bei der Codeeingabe verwendet wird.
Task Listen Kommentare
Visual Studio kann in Kommentaren nach bestimmten Token suchen und diese dann in der Task Liste gesammelt anzeigen. So können zum Beispiel Codestellen markiert werden, die noch einer Bearbeitung bedürfen. Vordefinierte Token sind TODO, HACK und UNDONE. Ein Token muss immer direkt hinter den Zeichen stehen, die den Kommentar einleiten.
// TODO Diese Zeile erscheint in der Task Liste
/* HACK Auch dieser mehrzeilige Kommentar
erscheint in der Task Liste */
Es können auch eigene Token erstellt werden.[2]
Doxygen Befehle
Wird ein Programm wie Doxygen verwendet, um aus dem Source Code automatisiert eine Dokumentation zu generieren, so können in den Kommentaren noch zusätzlich Special Commands[3] verwendet werden. Mit ihnen lassen sich zum Beispiel der Text formatieren oder man kann bestimmte Meta Informationen zum Code mitgeben.
Wie und was kommentieren?
...
Wie man NICHT kommentieren sollte
Manchmal ist es einfach leichter zu sagen, wie man es eben nicht machen sollte[4]:
Unterschätze die Zielgruppe nicht
Wer auch immer in den Code reinschauen wird, es wird sicherlich auch ein Entwickler (aus deinem Team?) sein. Solche Kommentare sind völlig unnötig und gehören raus:
ACHTUNG NEGATIVBEISPIEL!
//Initialisiere i mit 20
int i = 20;
Übertreibe es nicht
Wenn man aufgrund lauter Kommentare den Code selbst plötzlich suchen muss, dann wurde inzwischen bei weitem viel zu viel kommentiert. Innerhalb von Prozeduren sollten nur dann Kommentare verwendet werden, wenn es aus dem Code selbst nicht ersichtlich ist, was er tut (Clean Code Ansatz).
Trenne dich von altem Code
Lösche nicht mehr gebrauchten Code, anstatt ihn auszukommentieren. Ansonsten sammeln sich nach und nach im Quellcode immer mehr Codeleichen an, die völlig unnötig sind.
Du sollst nicht Fluchen
Selbst wenn dich gerade ein Stück Code in Rage versetzt, solltest du dich beim Schreiben eines Kommentars zurückhalten. Es ist gesünder für die Zusammenarbeit im Team und kann dich im Berufsleben im schlimmsten Fall den Job kosten.
Wann kommentieren?
Kommentieren ist schön und gut, aber wann genau soll nun kommentiert werden? Es gibt mehrere Ansätze, Kommentare zu verfassen, die auch von dem jeweiligen Programmierstil abhängen.
Bei einem geplanten Vorgehen überlegt man sich im Voraus, was der Code genau leisten soll. Dann spezifiziert man die Parameter und die Rückgabe und verfasst noch vor dem Implementieren einen Kommentar der genau beschreibt, was der Code leisten wird. Vorteil dieses Ansatzes ist, dass auf diese Weise Funktionen und Klassen markiert werden können, die man (oder ein anderer Entwickler) erst später implementieren wird. Solche Codestellen sollten unbedingt mit einem Task List Comment markieren:
// TODO kurze Beschreibung, was genau hier noch zu tun ist
Referenzen
- ↑ http://msdn.microsoft.com/en-us/library/5ast78ax.aspx Microsoft msdn - Recommended Tags for Documentation Comments (C# Programming Guide)
- ↑ http://msdn.microsoft.com/en-us/library/zce12xx2(VS.80).aspx Mircrosoft msdn Library - How to: Create Task List Comments
- ↑ http://www.stack.nl/~dimitri/doxygen/commands.html Doxygen Manual - Special Commands
- ↑ http://allthingsoracle.com/how-to-make-comments-the-most-important-code-you-write/ How to make comments the most important 'code' you write