Dokumentation: Unterschied zwischen den Versionen

Version vom 27. April 2012, 04:36 Uhr

Warum kommentieren?

...

Kommentare als Werkzeug

Visual Studio bietet verschiedene Möglichkeiten, Kommentare zu verfassen. Neben den Inline Kommentaren, die nur für kurze Anmerkungen verwendet werden sollten, gibt es noch mehrzeilige Kommentare und XML Kommentare, mit denen sich Meth

Einzeilige Kommentare (single line comment)

Einzeilige Kommentare beginnen mit zwei Slashes und enden automatisch am Ende der Zeile:

//Dies ist ein Inline Kommentar. Er endet automatisch am Ende der
//Zeile, so dass // in jeder Zeile wiederholt werden muss.

int i = 0; // Inline Kommentare können auch in der Mitte einer Zeile beginnen

Abgegrenzte Kommentare (delimited comment)

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

...

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.^[1]

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^[2] verwendet werden. Mit ihnen lassen sich zum Beispiel der Text formatieren oder man kann bestimmte Meta Informationen zum Code mitgeben.

Wie und was kommentieren?

...

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/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

[1] ttp://msdn.microsoft.com/en-us/library/zce12xx2(VS.80).aspx Mircrosoft Msdn Library - How to: Create Task List Comments

[2] ttp://www.stack.nl/~dimitri/doxygen/commands.html Doxygen Manual - Special Commands

[1]

[2]

@@ Zeile 1: / Zeile 1: @@
 {{UEA|Jeremi|Dieser Artikel wird gerade erstellt. Bitte haben Sie etwas Geduld. :)}}
-== Dokumentation ==
 {{BA|Jeremi|Hier kurze Einleitung}}
-<ref>[http://www.clean-code-developer.de/Source-Code-Konventionen.ashx Clean Code Developer - Source Code Konventionen]</ref>
+== Warum kommentieren? ==
-=== Warum kommentieren? ===
 ...
-=== Kommentare als Werkzeug ===
+== Kommentare als Werkzeug ==
 [[Visual Studio]] bietet verschiedene Möglichkeiten, Kommentare zu verfassen. Neben den ''Inline Kommentaren'', die nur für kurze Anmerkungen verwendet werden sollten, gibt es noch ''mehrzeilige Kommentare'' und ''XML Kommentare'', mit denen sich Meth
-==== Einzeilige Kommentare (single line comment) ====
+=== Einzeilige Kommentare (single line comment) ===
 Einzeilige Kommentare beginnen mit zwei Slashes und enden automatisch am Ende der Zeile:
@@ Zeile 24: / Zeile 21: @@
 </source>
-==== Abgegrenzte Kommentare (delimited comment) ====
+=== Abgegrenzte Kommentare (delimited comment) ===
 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>).
@@ Zeile 34: / Zeile 31: @@
 </source>
-==== XML Kommentare ====
+=== XML Kommentare ===
 ...
-==== Task Listen Kommentare ====
+=== Task Listen Kommentare ===
 Visual Studio kann in Kommentaren nach bestimmten Token suchen und diese dann in der [[Task List]]e 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.
@@ Zeile 49: / Zeile 46: @@
 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]]
-==== Doxygen Befehle ====
+=== 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''<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.
-=== Wie und was kommentieren? ===
+== Wie und was kommentieren? ==
 ...
-=== Wann kommentieren? ===
+== 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.