Anhang A der C # -Sprachspezifikation behandelt Dokumentationskommentare und gibt an, dass es zwei Formen gibt:
einzeiliger doc-Kommentar:
/// Eingabezeichenzeichenopt
Begrenzter-Doc-Kommentar:
/ ** delimited-comment-textopt * /
Gibt es eine Präferenz? Ich bemerke eine Tendenz, das Single-Line-Doc-Kommentar-Format zu bevorzugen, aber ich weiß nicht, ob es technische oder praktische Gründe gibt, neben den Leuten, die aus ästhetischer Sicht wählen.
Ich habe auch in dem Buch "C # for Java Developers" von Jones und Freeman Folgendes gelesen:
Vor den Kommentaren der Codedokumentation werden drei Schrägstriche angezeigt, wie hier gezeigt:
/// A single line documentation comment.
Die C # -Spezifikation empfiehlt außerdem die Verwendung des vertrauten / ** Tokens, um mehrzeilige Dokumentationskommentare zu identifizieren. Allerdings unterstützt Version 7.00 des C # -Compilers diese Syntax nicht.
Ich konnte nicht überprüfen, dass die neuesten Versionen des csc nicht mit der mehrzeiligen Syntax arbeiten. Soweit ich das beurteilen kann, funktioniert diese Syntax gut.
**edit** Einige Leute haben gebeten, eine Probe zu zeigen. Hier ist das Beispiel:
Also ist die Frage, neu formuliert, welche Form ist vorzuziehen, gibt es technische oder andere Gründe, den Dokumentationskommentarsstil von Methode1 in der obigen Probe oder Methode2 in der obigen Probe zu bevorzugen?
Info Ich konnte sammeln, da das Senden dieser Frage bestätigt, dass csc /doc: zwar beide Formate akzeptiert, das einzeilige Format jedoch einige Vorteile gegenüber dem mehrzeiligen Format hat:
1) In Visual Studio erhalten Sie in IntelliSense Informationen zur Klärung der Argumente, die Sie während der Eingabe in einem Methodenaufruf-Ausdruck übergeben, unabhängig davon, ob Sie Ihre Methode ursprünglich mit /// oder / ** dokumentiert haben. Visual Studio unterstützt Sie jedoch nur dann beim Schreiben von Dokumentationskommentaren, wenn Sie das Format "///" verwenden. Wenn Sie beispielsweise den Mauszeiger über einer Methodendeklaration in Visual Studio platzieren und dreimal / drücken, wird eine kontextspezifische Vorlage angezeigt, die wie folgt generiert wird:
%Vor%
Dies funktioniert nicht, wenn Sie den Cursor auf die Methode positionieren und / , * , * .
2) Das einzeilige Format ermöglicht ein saubereres Layout der Dokumentationskommentare, da jede Zeile mit der gleichen Einrückung beginnt, alle Zeilen des Blocks verwendet werden können und jede Zeile mit Kommentarinformationen linksbündig ist.
3) Es gibt im Allgemeinen Vorteile bei der Verwendung des einzeiligen Stils in dieser einzelnen Zeile. Kommentare können das * / Token frei enthalten, während mehrzeilige Kommentare dies nicht sind. und sie sind im Allgemeinen leichter zu bearbeiten, wenn Sie Teile von Kommentaren innerhalb eines Editors von einem Ort zum anderen kopieren / einfügen.
4) Es gibt auch Hinweise darauf, dass der C # -Compiler das Single-Line-Format bevorzugt, wenn Sie berücksichtigen, wie csc.exe mit benachbarten Dokumentationsblöcken umgeht. Betrachten Sie eine Erklärung wie folgt:
%Vor%
Beim Durchlaufen von csc / doc: Die Dokumentation wird generiert, als ob der Inhalt beider Blöcke die Main-Methode geändert hätte. Dieses Verhalten ist nicht intuitiv, wird aber intuitiv, wenn Sie die zwei angrenzenden mehrzeiligen Kommentarblöcke wie folgt in zwei aneinandergrenzende Sätze einzeiliger Kommentare umwandeln:
%Vor%
Ich habe bei der Verwendung von Sternchen über die doppelten (oder dreifachen) Schrägstriche nie irgendwelche Beschränkungen erfahren. Aus irgendeinem Grund hat die C # -Community entschieden, doppelte Schrägstriche für Kommentare zu verwenden.
Interessanterweise erscheinen die doppelten Schrägstriche aus C ++ und Java. Im Folgenden habe ich eine Liste von Sprachen und was einen Kommentar in der Sprache bezeichnet:
Im Folgenden finden Sie ein Beispiel für Werkzeuge, die doppelte Schrägstriche als einzeilige und doppelte Zeilenkommentare verwenden.
Visual Studio Markieren Sie einen Codeblock und verwenden Sie die Tastenkombination Strg + K + C, und der Code wird mit den doppelten Doppelstrichen auskommentiert.
Ghost Doc Ghost Doc ist ein Tool, das automatisch die Dokumentation für die Methode generiert. Es verwendet die dreifache Schrägstrichnotation. Es ist mein Verständnis, dass der dreifache Schrägstrich mit der Verwendung von XML-Elementen in den Kommentaren Werkzeug wie NDoc und Sandcastle generiert das HTML-Hilfeformat im MSDN-Stil.
Atomineer Pro Atomineer Pro ist ein weiteres Tool, das Methoden-Dokumentation aus den Methodennamen und Parameternamen generiert. Außerdem wurde standardmäßig die dreifache Schrägstrich-Notation verwendet.
MSDN C # -Kodierungsstandards Die C # -Kodierungsstandards sagen, den doppelten Schrägstrich zu verwenden und die Blockkommentare nicht zu verwenden .
iDesign C # -Kodierungsstandards Obwohl iDesign nicht Microsoft ist, hatte ich immer das Gefühl, dass sie eine Autorität in der C # -Community waren. Sie haben ein C # -Coding-Standard-Dokument veröffentlicht, das besagt, dass die doppelte Notation die bevorzugte Methode ist.
Tags und Links c# xml-documentation