XML-Tipps für C # -Programmierung [geschlossen] Kommentar

Question

Guter Morgen, Nachmittag, Abend oder Nacht (je nach Zeitzone).

Das ist nur eine allgemeine Frage zu XML in C # zu kommentieren. Ich habe noch nie sehr groß gewesen in meine Programme zu kommentieren, habe ich immer mehr eine ausführliche Variable / Eigenschaft / Methode namer gewesen und den Code im Stich gelassen sprechen für sich. Ich schreibe Kommentare, wenn ich etwas bin Codierung, die ziemlich verwirrend ist, aber zum größten Teil schreibe ich nicht eine Menge Kommentare.

ich tat einige Lesung über XML-Kommentare in .NET, Sandburg und die Hilfedatei Builder auf Codeplex und es hat mich abgehängt den Pfad zu wollen meinen Code und erzeugen ein paar nette, hilfreiche Dokumentation für diejenigen dokumentieren, die müssen graben sich in meinen Code, wenn ich nicht mehr hier bin.

Meine Frage bezieht sich auf Standards und Konventionen. Gibt es eine Anleitung für „gut“ XML zu kommentieren? Sollten Sie jede Variable und Eigentum kommentieren? Jede Methode? Ich suche im Grunde nur für Tipps, wie gut Kommentare zu schreiben, die von Sandburg in eine gute Dokumentation, so dass andere Programmierer zusammengestellt werden meinen Namen nicht fluchen, wenn sie am Ende mit auf meinen Code zu arbeiten.

Vielen Dank im Voraus für Ihre Ratschläge und Anregungen, Scott Vercuski

Answer 1

Persönlich stellen wir sicher, dass jede öffentliche und geschützte Methode XML Kommentare. Es wird Ihnen auch mit Intellisense bieten, und nicht nur Hilfe-Dokumentation Endbenutzer. In der Vergangenheit haben wir es auch auf privat scoped Erklärungen, aber nicht das Gefühl es ist zu 100% erforderlich, solange die Verfahren kurz sind und auf-Punkt.

Vergessen Sie nicht, dass es Werkzeuge, um Sie zu machen XML kommentieren Aufgaben einfacher:

• GhostDoc -. Kommentar Vererbung und Templating Add-In
• Sandcastle Help File Builder - Bearbeitet die Sandcastle-Projekte über eine GUI, kann von einer Befehlszeile ausgeführt werden (für Build-Automatisierung) und kann MAML für Hilfethemen bearbeiten nicht aus dem Code abgeleitet. (Die 1.8.0.0 Alpha-Version ist sehr stabil und sehr verbessert. Wurden sie etwa einen Monat jetzt mit mehr als 1.7.0.0)

Answer 2

Kommentare sind sehr oft veraltet. Dies war schon immer ein Problem gewesen. Meine Faustregel:. Je mehr Sie benötigen einen Kommentar zu aktualisieren, zu arbeiten, desto schneller das Kommentar veraltet sein

XML Kommentare sind für die API-Entwicklung. Sie funktioniert recht gut mit Intellisens und sie können haben Sie ein HTML-Hilfe-Dokument in kürzester Zeit erzeugen.

Das ist aber nicht frei: Beibehaltung wird schwer sein (siehe jeder nicht-triviales Beispiel, werden Sie verstehen, was ich meine), so neigen sie dazu, sehr schnell überholt sein. Als Ergebnis Überprüfung XML-Kommentare sollten als Pflichtprüfung und diese Überprüfung zu Ihrem Code-Review hinzugefügt werden soll jedes Mal, wenn eine Datei aktualisiert wird durchgeführt werden.

Nun, da es teuer ist, zu halten, da viele nicht-privater Symbole (in Nicht-API-Entwicklung) nur um 1 oder 2 Klassen verwendet werden, und da diese symboles oft selbsterklärend sind, würde ich nie erzwingen ein Regel, die besagt, dass jedes nicht-privaten Symbol sollte XML kommentiert. Das wäre viel des Guten und conterproductive . Was Sie erhalten ist, was ich an vielen Orten gesehen: fast leer XML Kommentare Hinzufügen nichts mit dem Namen symbole. Und Code, der nur ein wenig weniger lesbar ist ...

Ich denke, dass die sehr, sehr wichtige Führungslinie über Kommentare in normalen (nicht-API-Code) nicht über sein sollte, wie sie geschrieben werden sollten: , sondern über Was soll sie enthalten . Viele Entwickler immer noch nicht wissen, was zu schreiben. Eine Beschreibung dessen, was kommentiert werden, mit Beispielen, würde für Ihren Code besser als nur einer Ebene: „Sie XML-Kommentare zu jedem nicht-privaten Symbole verwenden“.

Answer 3

Ich dokumentiere öffentliche Klassen und die öffentlichen / Geschütztes Mitglieder dieser Klassen.

Ich dokumentiere nicht private oder interne Mitglieder oder interne Klassen. Daher Variablen (ich glaube, Sie Felder bedeuten), weil sie privat sind.

Das Ziel ist eine Dokumentation für einen Entwickler zu erstellen, die nicht bereit Zugriff auf den Quellcode haben.

Endeavour einige Beispiele zu platzieren, wo der Gebrauch nicht offensichtlich ist.

Answer 4

I Kommentar sehr selten auf Methodenvariablen, und ebenso selten Felder (da sie in der Regel durch eine Eigenschaft abgedeckt sind oder einfach nicht existieren automatisch implementierte Eigenschaften bei der Anwendung).

Generell versuche ich hart sinnvolle Kommentare zu allen öffentlichen / geschützten Mitglieder hinzuzufügen, was sehr praktisch ist, da, wenn Sie auf die XML-Kommentare während Build drehen, Sie automatische Warnungen erhalten für Kommentare fehlt. Je nach Komplexität könnte ich ausfüllen nicht jedes Detail - das heißt, wenn es zu 100% klar ist, was jeder Parameter hat zu tun (dh es gibt keine spezielle Logik, und es gibt nur 1 logische Art und Weise zu interpretieren die Variablen), dann I Macht faul und nicht kommentieren über die Parameter.

Aber ich versuche, auf jeden Fall zu beschreiben, welche Methoden, Typen, Eigenschaften, etc. darzustellen / zu tun.

Answer 5

Wir dokumentieren die öffentlichen Methoden / Eigenschaften / etc auf unseren Bibliotheken. Im Rahmen des Build-Prozesses verwenden NDoc wir eine MSDN-wie Web-Referenz zu erzeugen. Es war sehr hilfreich für eine schnelle Referenz und Lookup.

Es ist auch toll für Intellisense, vor allem mit den neuen Teammitgliedern oder, wie Sie gesagt haben, wenn der ursprüngliche Autor ist weg.

Ich bin einverstanden, dass Code in der Regel sollte selbsterklärend sein. Die XML-Dokumention, zu mir, ist mehr über Referenz- und Nachschlagen, wenn Sie nicht über die Quelle zu öffnen.

Answer 6

Persönlich meiner Meinung nach zu kommentieren zu vermeiden. Kommentierte ist gefährlich. Da in der Industrie wir immer Code aktualisieren (weil das Geschäft und Anforderungen immer ändern), aber variieren selten aktualisieren wir unsere Kommentare. Dies kann den Programmierer verleiten.