Dokumentation: Unterschied zwischen den Versionen

{{Review}}

Kommentieren macht den Programmcode für andere verständlicher. Jeder Entwickler wird dankbar über hilfreiche Kommentare sein, die ein persönliches Nachfragen und somit viel Zeit ersparen. Selbst wenn man nur alleine an einem Projekt arbeitet, sollte man sich fragen, ob das auch für die Zukunft gilt.

Gutes Kommentieren kann außerdem das Programm-Design verbessern.<ref>http://dkrukovsky.blogspot.de/2005/07/how-to-write-comments.html Make The Software Shine - How to Write Comments</ref> Wenn man nach dem [[CleanCode#Single_Responsibility_Principle_.28SRP.29|Single Responsibility Principle (SRP)]] vorgeht, so kann man jede Klasse mit ihrem Verantwortungsbereich mit einem Kommentar markieren. Auf diese Weise kann man stetig kontrollieren, ob die Klasse in ihrem Verantwortungsfeld operiert, und das Implementieren von Aufgaben vermeiden, wenn diese nicht zur Klasse gehören.

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 beginnen mit zwei Slashes und enden automatisch am Ende der Zeile:

</source> [[Kategorie:Code-Beispiele]]

{{BA|Jeremi|im englischen: "delimited comments"}}

Ein Stern nach einem Slash (<code>/*</code>) leitet einen Kommentarblock ein. Der Kommentar endet erst, wenn das das entsprechende Token zum beenden des abgegrenzten Kommentars gefunden wurde (<code>*/</code>).

</source> [[Kategorie:Code-Beispiele]]

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 (<code>/</code>) ein, so werden anhand der Signatur der Funktion automatisch die notwendigen XML Tags erstellt.

Praktisch an XML Kommentaren ist, dass diese automatisch in einem Tooltip erscheinen, wenn die entsprechend dokumentierte Klasse, Funktion, etc. bei der Codeeingabe verwendet wird.

Visual Studio kann in Kommentaren nach bestimmten Token suchen und diese dann in der [[Aufgabenliste]] 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.

Es können auch eigene Token erstellt werden.<ref>http://msdn.microsoft.com/en-us/library/zce12xx2(VS.80).aspx Mircrosoft msdn Library - How to: Create Task List Comments</ref> [[Kategorie:Code-Beispiele]]

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''<ref>http://www.stack.nl/~dimitri/doxygen/commands.html Doxygen Manual - Special Commands</ref> verwendet werden. Mit ihnen lassen sich zum Beispiel der Text formatieren oder man kann bestimmte Meta Informationen zum Code mitgeben.

Nach den [[CleanCode|Clean Code Prinzip]] sollte ein Programm sich selbst beschreiben und mit möglichst wenigen Kommentaren auskommen<ref>http://www.clean-code-developer.de/Source-Code-Konventionen.ashx Clean Code Developer - Source Code Konventionen</ref>:

</source> [[Kategorie:Code-Beispiele]]

Klassen Methoden, Prozeduren, Funktionen, etc. sollten mit [[Dokumentation#XML_Kommentare|XML Kommentaren]]  versehen werden. Diese werden verwendet um die automatisierte Dokumentation zu bauen.

Außerdem werden XML Kommentare dazu verwendet, bei der Codeeingabe Hinweise in einer Tooltip Box anzuzeigen, so dass das arbeiten mit dokumentierten Funktionen deutlich leichter fällt. [[Kategorie:Code-Beispiele]]

{{BA|Jeremi|Hier auf Parameter der XML Kommentare eingehen? So kommt sicher die Frage, ob nun ein Parameter, der in der summary beschrieben wurde jetzt auch nochmal einzeln beschrieben werden muss -> ja!}}

Manchmal ist es einfach leichter zu sagen, wie man es eben nicht machen sollte<ref>http://allthingsoracle.com/how-to-make-comments-the-most-important-code-you-write/ How to make comments the most important 'code' you write</ref>:

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:

</source>

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).

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.

{{BA|Jeremi|Natürlich ist das nicht super streng gemeint. Beim Testen kann durchaus Code auskommentiert werden. Spätestens beim Commit ins SVN sollte das aber raus}}

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. [[Kategorie:Code-Beispiele]]

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.  

Ein guter Richtwert ist: ''Wenn man ins SVN eincheckt, dann sollte alles kommentiert sein!'' (Einchecken sollte man sowieso nur sauberer Code.)

[[Kategorie:Best Practice Programmierung]]