Welche Informationen in Xml-Kommentaren zu liefern?

Question

Wenn ich eine Methode schreibe und sie kommentieren möchte, schreibe ich die gleiche Information in die Zusammenfassung.

Beispiel:

/// <summary> 
/// Get a <typeparamref name="Customer">customer</typeparamref> by its ID 
/// </summary> 
/// <param name="id">customer id</param> 
/// <returns>a <typeparamref name="Customer">customer</typeparamref></returns> 
private Customer GetCustomerById(string id) 
{ 
    ... 
} 

Schließlich ist es das wirklich nützlich? Welche Informationen liefern und in welchem ​​Tag liefern sie?

Answer 1

Betrachten Sie DRY (wiederholen Sie nicht). Der Parameter param beschreibt den Parameter und der Rückgabeeintrag beschreibt, was zurückgegeben wird. Die Zusammenfassung sollte einen Überblick darüber geben, was die Methode macht, und nicht die Informationen aus diesen anderen Einträgen wiederholen.

Was Ihre Dokumentation fehlt, ist die eigentliche Dokumentation. Eine "String-ID" ist eine Zeichenfolge, die eine ID enthält - das ist selbstdokumentierend. Aber wie rufe ich diese Methode auf: Was beinhaltet eine gültige Benutzerkennung? Was passiert, wenn ich eine leere oder leere Zeichenfolge übergebe?

usw.

Hier ist ein hypothetisches Beispiel, die Dokumentation von dem, was die Dinge sind und wie verwenden, um das Verfahren umfasst:

/// <summary> Gets information on a customer </summary> 
/// 
/// <param name='id'> A customer identifier in the form of a GUID string. 
/// e.g. "{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}". 
/// Braces around the GUID are optional. 
/// This parameter must be a valid Guid. </param> 
/// 
/// <returns> A Customer record describing the given customer, or 
/// null if the Customer is not found</returns> 

Wenn Sie dann diese Art von Parametern Details zu replizieren verwenden ein Tool wie mein AddIn (Atomineer Pro Documentation) um eine Klasse herum ist trivial, so dass es nicht zeitaufwändig sein muss, Ihre Methoden gut zu dokumentieren.

Answer 2

Eine Antwort auf eine andere Frage auf deine Antwort auch:

Ist Dokumentation bietet wirklich nützlich?

Geben Sie alles, was Sie wollen, was Sie sehen benötigt und nützlich. Diese Informationen werden einem Code-Consumer in Visual Studio als IntelliSense-Tooltip angezeigt, wie Sie für .NET-Klassen und -Elemente sehen.

Answer 3

Xml-Dokumentation ist sehr nützlich, wenn Sie eine Bibliothek entwickeln. Für diese XML-Kommentare kann automatisch eine Hilfedatei generiert werden. Ausführliche Erläuterungen zum Generieren der Hilfedatei finden Sie unter this. Informationen zum Xml-Dokumentations-Tag finden Sie unter MSDN.

Answer 4

Manchmal sind Methoden- oder Eigenschaftsnamen selbsterklärend, aber das ist nicht immer der Fall. Ereignis mit Ihrem Beispiel Sie sollten Informationen bereitstellen, was passiert, wenn die angegebene ID nicht existiert. Wird Ihre Methode eine Exception auslösen (wenn ja, welche Exception wäre das) oder vielleicht nur null oder eine Art allgemeinen Customer.Empty-Wert zurückgeben? Manchmal könnten Sie sogar ein Codebeispiel bereitstellen.

In jedem Fall ist es immer eine gute Methode, Code-Dokumentation in jedem Fall zur Verfügung zu stellen.

Answer 5

In vielen Fällen finde ich es am besten, das Rückführelement komplett auszuschneiden. Es scheint, als ob dein Beispiel ein großartiges Beispiel dafür ist. Zum Glück markiert VStudio dies nicht als einen schlechten Kommentar mit einer Warnung. Der Grund, warum ich das tue, ist, dass in 80% der Fälle meine Dokumentation im Grunde beschreibt, worum es beim Rückgabetyp geht, oder ob der Name der Funktion so offensichtlich ist, dass es eine sinnlose Verschwendung von Zeit und Energie ist meine Schätzung, um dies zu berücksichtigen, und es führt oft zu einer Verletzung von DRY.

Ihr Beispiel ist ein perfektes Beispiel dafür.

Customer GetCustomerById(string id) 

Wenn dies eine int id ist, kann diese Funktion nicht einmal einen Kommentar benötigen. Mit einer Schnur ist das weniger klar und kann etwas Klärung erfordern. In beiden Fällen scheint es jedoch eine Verschwendung zu sein, einen XML-Kommentar zum Rückgabetyp bereitzustellen. Denken Sie daran, dies ist eine subjektive Frage, einige Leute mögen um der Vollständigkeit halber immer den Rückgabetyp Kommentar, das ist in Ordnung. Ich bin froh, dass es nicht erforderlich ist, angefangen mit VStudios Warnsystem.