Was sind Best Practices für das Dokumentieren C # -Code mit XML-Kommentare?

StackOverflow https://stackoverflow.com/questions/3143324

  •  01-10-2019
  •  | 
  •  

Frage

Ich werde durch einigen neuen Code, den ich gerade geschrieben und das Hinzufügen von NDoc sytle Kommentare zu meinen Klassen und Methoden. Ich hoffe, ein ziemlich guten MSDN Stil Dokument als Referenz zu erzeugen.

In der Regel, was sind einige gute Richtlinien, wenn Sie Kommentare für eine Klasse und ein Verfahren zu schreiben? Was soll sagen die NDoc Kommentare? Was sollten sie nicht sagen?

Ich finde mich zu schauen, was die .NET-Framework Kommentare sagen, aber das wird schnell alt; wenn ich ein paar gute Regeln selbst zu führen haben könnte, konnte ich meine docs viel schneller beenden.

War es hilfreich?

Lösung

In den Kommentaren zu Build-API-Dokumentation verwendet, sollen Sie:

  • Erklären Sie, was die Methode oder Eigenschaft der Fall ist, warum es überhaupt existiert, und erklären Sie alle Domänen Konzepte, die nicht selbstverständlich für den durchschnittlichen Verbraucher Ihres Codes sind.

  • Liste alle Voraussetzungen für Ihre Parameter (kann nicht null sein, innerhalb eines bestimmten Bereichs sein muss, usw.)

  • Liste alle Nachbedingungen, die beeinflussen können, wie Anrufer mit Rückgabewerten befassen.

  • Liste Ausnahmen die Methode werfen können (und unter welchen Umständen).

  • Wenn ähnliche Methoden existieren, erklärt die Unterschiede zwischen ihnen.

  • Anruf Aufmerksamkeit auf etwas Unerwartetes (wie globalen Zustand zu ändern).

  • Aufzählen irgendwelche Nebenwirkungen, wenn es welche gibt.

Andere Tipps

Wenn Sie mit Kommentaren am Ende, dass jeder Wert nicht stimmen, sind sie nur verschwenderisch.

Zum Beispiel 

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

... Sie selbst hinzugefügt haben absolut keinen Wert und nur hinzugefügt mehr Code zu erhalten.

Zu oft Code wird mit diesen überflüssigen Kommentaren übersät.

StyleCop liefert Hinweise für Code und zu kommentieren Stil. Die Vorschläge gibt es im Einklang mit dem MSDN-Dokumentation Stil.

Was den Inhalt des Kommentars, sollte es dem Benutzer Ihres Codes genug Informationen geben, welche Art von Verhalten zu erwarten. Es sollte auch mögliche Fragen beantwortet die Benutzer haben könnten. Also versuchen Sie den Code als jemand zu verwenden, die nichts über den Code nicht kennt, oder noch besser, fragen Sie jemand anderes zu tun.

Eigenschaften sollte Ihr Kommentar angeben, ob die Eigenschaft nur gelesen wird, Schreib nur oder Lese-Schreib. Wenn Sie bei allen offiziellen MS-Dokumentation schauen, Immobilien doc Kommentare beginnen immer mit „Ruft ...“, „Ermittelt oder legt fest ...“ und (sehr selten, vermeiden Schreib nur Eigenschaften in der Regel) „Sets ...“

Vergessen Sie nicht, was ist ein gültiges XML ist. Zum Beispiel: 

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

(Fehler: ungültige XML).

Ich schreibe die

Kommentar die Informationen aufzunehmen Ich möchte wissen, ob ich derjenige war, dass die Funktion aufgerufen wird (oder diese Klasse instanziieren).

Ich schreibe den Kommentar Information enthalten Ich möchte wissen, ob ich mit dem Debuggen oder zu verbessern, dass die Funktion oder Klasse beauftragt wurde. Hinweis: Dies ersetzt nicht die Notwendigkeit für eine gute Inline-Kommentare. Aber manchmal ein allgemeiner Überblick über das Innenleben der Funktion / Klasse ist sehr hilfreich.

angegeben Wie auf der MSDN-Seite , verwenden Sie XML-Dokumentation Kommentare Dokumentation automatisch zu erzeugen, so dass es Entscheidungsträgern sinnvoll, wenn Sie eine API und wollen nicht arbeiten zweimal an beiden Code und Dokumentation, mit dem zusätzlichen Vorteil, halten sie synchron sind schriftlich - jedes Mal, wenn Sie den Code ändern, ändern Sie die entsprechenden Kommentare und die Dokumentation regenerieren.

Compile mit /doc und dem Compiler wird für alle XML-Tags im Quellcode suchen und eine XML-Dokumentationsdatei erstellen, verwendet dann ein Tool wie Sandcastle die vollständigen Dokumente zu erzeugen.

Eine Sache, über Kommentare aktualisiert sie. Zu viele Menschen verändern, um eine Funktion dann nicht den Kommentar ändern, um die Änderung widerzuspiegeln.

Lizenziert unter: CC-BY-SA mit Zuschreibung
Nicht verbunden mit StackOverflow
scroll top