it-swarm.com.de

Kommentieren Sie die Schnittstelle, die Implementierung oder beides?

Ich kann mir vorstellen, dass wir alle (wenn wir gestört werden können) unsere Schnittstellen kommentieren. z.B.

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

Kommentieren Sie auch die Implementierung (die möglicherweise auch Clients zur Verfügung gestellt wird, beispielsweise als Teil einer Bibliothek)? Wenn ja, wie schaffen Sie es, die beiden synchron zu halten? Oder fügen Sie einfach den Kommentar "Schnittstelle für Dokumentation anzeigen" hinzu?

Vielen Dank

108
ng5000

Generell verwende ich dasselbe Prinzip wie bei Code: DRY (Don't Repeat Yourself):

  • auf der Schnittstelle dokumentieren Sie die Schnittstelle
  • dokumentieren Sie bei der Implementierung die Implementierungsspezifikationen

Java-spezifisch: Wenn Sie die Implementierung dokumentieren, verwenden Sie das Tag {@inheritDoc}, um die Javadocs von der Schnittstelle aus einzuschließen.

Für mehr Informationen:

87
Neeme Praks

Wenn Sie das GhostDoc addin verwenden, wird die Implementierung mit dem Kommentar der Benutzeroberfläche aktualisiert, wenn Sie mit der rechten Maustaste klicken und "Document This" für die Methode auswählen.

7
NikolaiDante

Für C # kommt es auf IMO an: Wenn Sie explizite Schnittstellenimplementierungen verwenden, würde ich die Implementierung nicht dokumentieren.

Wenn Sie die Schnittstelle jedoch direkt implementieren und die Mitglieder der Schnittstelle mit Ihrem Objekt verfügbar machen, müssen auch diese Methoden dokumentiert werden.

Wie Nath sagte, können Sie GhostDoc verwenden, um die Dokumentation einer Schnittstelle automatisch in die Implementierung einzufügen. Ich habe das Dokument Dieser Befehl auf die Tastenkombination Strg + Umschalt + D und einen der Tastenanschläge, die ich fast automatisch drücke, zugeordnet. Ich glaube, ReSharper hat auch die Möglichkeit, die Dokumentation der Schnittstelle einzufügen, wenn die Methoden für Sie implementiert werden.

4
grover

Wir kommentieren nur die Benutzeroberfläche. Kommentare lassen sich so leicht mit der abgeleiteten Klasse oder der Basisklasse/der Benutzeroberfläche synchronisieren, dass es einfach ist, sie an nur einer Stelle zu haben.

Obwohl es so aussieht, als würde @Nath ein automatisiertes Dokumentationswerkzeug vorschlagen, das die Dinge zusammenhält (klingt cool, wenn Sie das verwenden). Hier bei WhereIWorkAndYouDontCare sind die Kommentare für dev, daher wird eine einzige Stelle im Code bevorzugt

4
Jiminy

Nur die Schnittstelle. Beides zu kommentieren ist eine Duplizierung und es ist wahrscheinlich, dass die beiden Sätze von Kommentaren möglicherweise nicht mehr synchron sind, wenn sich der Code ändert. Kommentieren Sie die Implementierung mit "implementiert MyInterface" ... Dinge wie Doxygen generieren Dokumente, die die abgeleiteten Dokumente in die Dokumente für die Implementierung enthalten (wenn Sie sie richtig eingerichtet haben).

3
Len Holgate

Das Kommentieren der Schnittstelle sollte ausreichend Dokumentation enthalten, um herauszufinden, wie die tatsächliche Implementierung verwendet wird. Das einzige Mal, wenn ich Kommentare zur Implementierung hinzufügen würde, ist, wenn sie über private Funktionen verfügt, die der Schnittstelle entsprechen, jedoch nur interne Kommentare sind und nicht in der Online-Dokumentation oder für Clients verfügbar sind.

Implementierungen sind nur das, solange sie der Schnittstelle entsprechen, müssen sie nicht separat dokumentiert werden.

2
X-Istence

Ich habe ein Tool erstellt, das die XML-Dokumentationsdateien nachverarbeitet, um Unterstützung für das <<originitdoc /> -Tag hinzuzufügen.

Mit Intellisense im Quellcode ist dies zwar nicht hilfreich, die modifizierten XML-Dokumentationsdateien können jedoch in einem NuGet-Paket enthalten sein und funktionieren daher mit Intellisense in referenzierten NuGet-Paketen.

Es ist bei www.inheritdoc.io (kostenlose Version verfügbar).

0
K Johnson

Sie können sicherlich beide kommentieren, haben dann aber das Problem, beide zu pflegen (wie bereits erwähnt). Wird jedoch heutzutage ein konsumierender Code IoC/DI wirklich nicht verwenden und die Schnittstelle nicht verwenden? Aus diesem Grund würde ich dringend empfehlen, die Benutzeroberfläche zu kommentieren, wenn Sie sich nur die Mühe machen möchten, eine zu kommentieren. Auf diese Weise erhält der Benutzer Ihres Codes höchstwahrscheinlich die Hinweise zu Nice Intellisense.

0
bytedev