Schnittstelle, Implementierung oder beides kommentieren?

Ich stelle mir vor, 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 auch Clients zur Verfügung gestellt werden kann, z. B. als Teil einer Bibliothek)? Wenn ja, wie schaffen Sie es, die beiden synchron zu halten? Oder fügen Sie einfach einen Kommentar "Dokumentation finden Sie in der Benutzeroberfläche" hinzu?

Vielen Dank

In der Regel verwende ich das gleiche DRY-Prinzip (Don't Repeat Yourself) wie beim Code:

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

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

Für mehr Informationen:

• Offizielle Javadoc-Dokumentation
• Einige inoffizielle Ratschläge .

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

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 den Befehl Dokument Dieser Befehl der Tastenkombination Strg + Umschalt + D und einem der Tastenanschläge zugeordnet, die ich fast automatisch drücke. Ich glaube, ReSharper hat auch die Möglichkeit, die Dokumentation der Schnittstelle einzufügen, wenn es die Methoden für Sie implementiert.

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

Wir kommentieren nur die Benutzeroberfläche. Kommentare sind so einfach nicht mehr mit der abgeleiteten oder der Basisklasse / Schnittstelle zu synchronisieren, dass es schön ist, sie an nur einem Ort zu haben.

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

Das Kommentieren der Benutzeroberfläche sollte ausreichend dokumentiert sein, um herauszufinden, wie die tatsächliche Implementierung verwendet wird. Das einzige Mal, dass ich der Implementierung Kommentare hinzufügen würde, ist, wenn sie private Funktionen enthält, die eingefügt wurden, um die Schnittstelle zu erfüllen. Es handelt sich jedoch nur um interne Kommentare, die nicht in der Online-Dokumentation oder für Clients verfügbar sind.

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

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

Es hilft zwar nicht mit Intellisense im Quellcode, ermöglicht jedoch die Aufnahme der geänderten XML-Dokumentationsdateien in ein NuGet-Paket und funktioniert daher mit Intellisense in NuGet-Paketen, auf die verwiesen wird.

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

Sie können sicherlich beide kommentieren, aber dann haben Sie das Problem, beide zu pflegen (wie bereits erwähnt). Wird heutzutage in der heutigen Zeit ein konsumierender Code wirklich kein IoC / DI verwenden und die Schnittstelle nicht verwenden? In Anbetracht dessen würde ich dringend empfehlen, die Benutzeroberfläche zu kommentieren, wenn Sie nur einen kommentieren möchten. Auf diese Weise erhält der Verbraucher Ihres Codes höchstwahrscheinlich die netten Intellisense-Hinweise.

C # -Verwendung:

Die Benutzeroberfläche kann folgendermaßen aussehen:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

Die Implementierung kann folgendermaßen aussehen:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}