Hallo Zusammen, schon wieder ein Bedürfnis das Meinungen benötigt. :-)
So wie ich es bis jetzt realisiert habe gibt es mehre Kommentar-Möglichkeiten, Klassen, Methoden u.s.w. zu beschreiben.
1.

[Description("Komentar")]
public void Function() {}

2.

/// <summary>Kommentar</summary>
public void Function() {}

3.

/* Kommentar */
public void Function1() {}
// Kommentar
public void Function2() {}

Viele von den Kommentar-Möglichkeiten lassen sich auf alle Elemente (Klassen, Methoden, u.s.w.) anwenden. Nun habe ich raus gefunden dass z.B. für den Objektexplorer die Kommentar-Möglichkeit (1) wichtig ist. Das gilt auch für eingebundene Assemblies.

Die dritte Möglichkeit verwende ich momentan für interne Beschreibung.

Meine Frage ist also: Wofür wird die zweite Möglichkeit verwendet? Wenn es eine Sinnvolle Funktion hat, möchte ich ungern immer (1) und (2) parallel verwenden wegen der Wartbarkeit und Tipparbeit.

Wie Dokumentiert Ihr euren Programm-Code in VS? Welche Tools sind erwähnenswert?

Ich kenne von anderen Programmierumgebung (Linux) ähnliche Kommentar-Möglichkeiten wie (2) die mit Tools schön aufbereitet werden können. Bei VS habe ich dies noch nicht gefunden, außer der Möglichkeit (1) und dem ObjektExplorer.

/** @brief Komentar */
public void Function2() {}

Vielen Dank; Grüße smartic

Ich würde ebenfalls die 2. Variante bevorzugen.

Und zwar nach folgendem Schema:

/// <summary>Grundlegende Beschreibung was die Funktion tut</summary>
/// <param name="name">Beschreibung des Parameters "Name"</param>
/// <param name="alter">Beschreibung des Parameters "Alter"</param>
/// <returns>Was gibt die Funktion zurück?</returns>
/// <remarks>Eine ausführlichere Beschreibung der Funktion wenn nötig</remarks>

Wenn die Funktion Fehler schmeißen kann
/// <exception cref="System.IO.FileNotFoundExceptionB">Beschreibung wann und warum diese Exception geworfen wird.</exception>

Bei generischen Typen wie List<T>
/// <typeparam name="T">The element type of the list</typeparam>

Für Properties
/// <value>The Name property gets/sets the _name data member.</value>

Bei Toolkits und Bibliotheken auf jeden Fall zu empfehlen - die ein Stück Beispielcode:
/// <example> 
/// Dieses Beispiel zeigt die Verwendung der String-Extension <see cref="Left"/>.
/// <code>
///     "MyString".Left(3);
///     //Returns: "MyS"
/// </code>
/// </example>

Ausführliche Informationen zu den XML-Kommentaren und welche es noch gibt findest du in der MSDN unter:
Empfohlene Tags für Dokumentationskommentare (C#-Programmierhandbuch)

Zwei der Grundlegenden Vorteile dieser Variante sind:
1. die Beschreibungen werden vom IntelliSense gelesen und angezeigt



2. du kannst mit Tools wie SandCastel oder GhostDoc dir Hilfedateie und API-Dokumentationen erstellen lassen wie diese hier:

Ich verwende GhostDoc.
Die Free-Edition hat bislang gut gereicht.

Edit:
In Visual Studio gibt es bei den Projekteigenschaften unter

Build -> Output -> XML documentation file

eine Checkbox. Wird diese gesetzt und ein Pfad zur XML-Datei angegeben, wirst du gezwungen, jede öffentliche Klasse und Methode mit Kommentaren zu versehen (zumindest bei Warning level4 und bei der Einstellung "Treat warnings as errors -> All"), was auch auf jeden Fall Sinn macht.
Als Fehlermelder erhält man :

Warning as Error: Missing XML comment for publicly visible type or member

also beim kurzen ausprobieren: Deine "2. Möglichkeit" wird von VS benutzt, um Tooltips anzuzeigen.

Das DescriptionAttribute (1.) wird verwendet, um das Item in visuellen Designern (WindowsForms-Designer für Controls, PropertyGrid in einer eigenen Anwendung etc.) zu beschreiben. Dass der "Objektexplorer" (=Objektbrowser?) sich darauf abstützt, wäre mir neu.

Mit der Variante 2 dokumentierst Du die API. Mit den richtigen Tools (z.B. Sandcastle) kannst Du daraus Hilfe-Dateien (*.chm) generieren oder auch sowas schönes wie die MSDN-Hilfe. Und ganz unmittelbar nutzt es Dir, weil VS das für Intellisense-Tooltips benutzt, wie nabuchodonossor schon angemerkt hat.

Variante 3 ist für "normale" Code-Kommentare wie "die nächsten 3 Zeilen sind ein schrecklicher Hack, aber ich hatte keine Zeit" ;-)

Du solltest, als Faustregel, möglichst reichlich von Variante 2 Gebrauch machen. Die ist auch deutlich ausdrucksstärker und mächtiger als Variante 1, die eher für spezielle Einsatzszenarien in Frage kommt. Beide richten sich aber an unterschiedliche Zielgruppen, weshalb es durchaus sinnvoll sein kann, beide parallel (normalerweise dann mit unterschiedlichen Texten) zu verwenden.