Was sind die Tugenden XML-Kommentare in .NET zu verwenden?

Question

Ich kann nicht die Tugenden versteht XML-Kommentare zu verwenden. Ich weiß, können sie in schöner Dokumentation, um den Code externe umgewandelt werden, aber das gleiche kann mit der vielen prägnanten Doxygen Syntax erreicht werden. Meiner Meinung nach sind die XML-Kommentare falsch, denn:

1. Sie verschleiern die Kommentare und den Code im Allgemeinen. (Sie sind schwieriger von Menschen zu lesen).
2. Weniger Code kann auf einem einzigen Bildschirm angezeigt werden, weil „Zusammenfassung“ und „/ Übersicht“ zusätzliche Leitungen nehmen.
3. (entfernt)

Was dann die Gründe gewesen sein könnte, warum XML in .NET bevorzugt wurde vielmehr, dass die einfache Doxygen Syntax?

Answer 1

Es gibt nicht wirklich eine richtige Antwort hier imo. Keines der Systeme ist „besser“ als die anderen in der Realität -. Sie beide die gleiche Arbeit am Ende tun, die Sie ist erlaubt Code-Dokumentation zu generieren

Die endgültige Ausgabe kann auf genau die gleiche Art und Weise für jeden von ihnen formatiert werden, und sie haben so ziemlich die gleiche Funktionalität in Hinblick darauf, was Etiketten etc sie unterstützen, so dass sie wirklich die persönliche Wahl hier.

Persönlich finde ich XML-Kommentare viel menschlicher lesbar zu sein, viel logischer und einfach nur einfach zu bedienen - das ist aber mit dem zusätzlichen Vorteil, dass Visual Studio automatisch Stubs für mich, um nur fill erzeugen und die hervorragende Unterstützung es hat zum Zusammen sie so viel Platz auf dem Bildschirm nehmen sie nicht auf. Ich bin sicher, dass jemand, der aus einer Bearbeitung im Hintergrund in VI oder some_other_IDE eine andere Meinung haben kommt, aber es gibt keinen wirklichen Vorteil entweder.

Also habe ich das wirklich sagen würde, es hängt davon ab, was IDE Sie verwenden, und was Sie und Ihr Team werden verwendet, um mit.

Wenn Sie nun fragen, warum Microsoft entschieden hat, so eng zu integrieren mit XML in Visual Studio zu kommentieren, die eine andere Frage. Wahrscheinlich ist es aufgrund der Tatsache, dass: es wäre einfacher, für sie innerhalb VS implementieren (wie sie wiederverwenden können vorhandenen Code zu generieren / die Kommentare und Build intellisense etc lesen), sie haben eine Tendenz zu „Standards für das Haften "sowieso (es ihre eigenen oder in der Industrie diejenigen sein), und auch aus Gründen der Lizenzierung wie von Jeff erwähnt.

Just hinzuzufügen, dass das Produkt Microsoft innerhalb VS verwendet wird „Sandcastle“ genannt, das ist eine interne XML-doc-Generierungs-Tool. Es hat seine eigene Wiki-Seite @ http://docproject.codeplex.com/Wikipage

Answer 2

1. Die ide nimmt den Kommentaren und zeigt ihnen, wenn diese Methode verwendet wird.
2. Jeder, der Programme C # wohl vertraut ist mit der XML-System zu kommentieren. Es gibt weniger für eine Neueinstellung zu lernen.

Ich sage nicht, dass Doxygen nicht besser ist, es ist nur, dass die xml zu kommentieren ist jedem bekannt, und das geht einem langen Weg. Es ist nur eine Sache weniger, Sie eine Neueinstellung zu trainieren, zu tun haben.

Soweit verlassen Variablen unkommentiert. Was ist für Sie selbstverständlich sein, nicht jemand anderes sein (oder Sie 6 Monate später).

Ok jetzt denke ich, ich sehe, was ihr bittet.

1. Verschleierung Kommentare. Die Farbcodierung hilft. Ich persönlich scannen schnell vorbei an dem grauen Text und nur lesen, was grün ist, wenn ich den XML-Text lesen muß. (In meinen Einstellungen zumindest).

2. Wir haben große Monitore, so dass wir mehr Code auf dem Bildschirm in der Regel erhalten. (Es ist billiger, einen großen Monitor zu kaufen, als umschulen Menschen im Allgemeinen). Die andere Sache, über zu diesem, ist, dass ich wette, Sie sind aktiv nur an einer Funktion zu einem Zeitpunkt suchen, also wenn das gesamte Funktion passt auf eine Seite, werden Sie wahrscheinlich nicht zu viel leiden nicht mehr Code zu sehen. Wenn nun die Funktionen lang sind, dann konnte ich sehen, dass ein Problem zu sein.

3. Wir stellen die Zusammenfassung Kommentare in einer einzigen Zeile, wenn möglich (vorausgesetzt, es ist nicht wirklich groß ist). Das senkt sich auf den aktuell verfügbaren Raum.

4. Ich weiß nicht, ob Doxygen dies tut, aber Sie können die Kommentare zusammenbrechen, so dass sie von dem Weg aus.

Answer 3

Die primäre Aufgabe von XML-Dokumentation ist nicht Dokumentation zu erzeugen. Es ist gut, IntelliSense Informationen für die Kunden Ihrer Klasse zu liefern. Versenden Sie die erzeugte XML-Datei zusammen mit Ihrer Montage.

Answer 4

Die Tugenden XML-Kommentare der Verwendung in .NET

Sie werden nativ durch die C # -Compiler und Visual Studio unterstützt wird, eine einzelne Lage bietet API für die Verwendung in gedruckten, online zu dokumentieren und IntelliSense-Dokumentation.

Dieser Artikel von MSDN Magazin folgenden Zustände an:

  

In jedem Projekt gibt es jemanden,   ist mit der Dokumentation nicht glücklich.   Der Teamleiter will mehr Kommentare in   die Quelle, technische Redakteure wollen   Weitere Informationen über die geschrieben   Code-Design, Qualitätssicherung will   um zu sehen, funktionale Spezifikationen und   bald. Wenn alle diese Dokumente sind   tatsächlich geschrieben, haben Sie immer noch die   Schlacht von allen von ihnen zu halten   synchronisiert.

Während das Format nicht unbedingt ideal ist, XML-Dokumentation Kommentare bieten eine reiche Syntax, so dass dies erreicht werden kann.

Warum unterstützt doxygen in C # nicht statt?

Was, warum das vorhandene XML-System über Doxygen gewählt wurde, würde ich vermuten, dass dies in erster Linie, weil Doxygen ist unter dem frei GPL der Visual Studio und der C # -Compiler würde auch Notwendigkeit bedeuten würde veröffentlicht als solche zu - etwas, dass Microsoft kein Zweifel nicht tun wollen unter Berücksichtigung der Bedingungen der GPL .

Answer 5

Ich finde, was noch mehr mindblowing ist die Popularität des GhostDoc Plugin. Wenn Sie automatisch einen Kommentar auf der Basis eines Methodennamen erzeugen können, warum überhaupt Kommentar hat?

Steve Yegge sagt, dass über Kommentierung ist das Zeichen für einen Neuling Programmierer, ich habe eine harte Zeit mit ihm nicht einverstanden.

Answer 6

Sie müssen nicht Haben verwenden, um sie in Ihren Projekten.

Sie sind a Standard, der in Visual Studio integriert werden passiert, und wenn Sie StyleCop verwenden können sie durchgesetzt werden. Das ist also der Grund hier.

Allerdings, wenn Sie sich entscheiden, Doxygen verwenden dann gibt es nichts mehr im Wege stehen. So stellen Sie sicher, dass Sie konsistent sind.